Description
A $ref in examples must point to an Example Object. A schema describes a data structure rather than an example value, so it cannot replace the example object.
Potential impact
Examples may be missing from API documentation, or users may misunderstand the expected request data.
Remediation
Reference shared examples through #/components/examples/... and check that their values match the relevant schema. Valid external Example Objects may also be referenced.
Examples
These examples replace the reference to the Address schema with a reference to an Address Example Object containing an actual address value.
Before
json
{
"openapi": "3.0.0",
"info": {
"title": "Simple API overview",
"version": "1.0.0"
},
"components": {
"securitySchemes": {
"regularSecurity": {
"type": "http",
"scheme": "basic"
}
},
"schemas": {
"ErrorModel": {
"type": "object",
"properties": {
"code": {
"type": "string"
}
}
},
"Address": {
"type": "object",
"properties": {
"street": {
"type": "string"
}
},
"required": [
"street"
]
}
}
},
"paths": {
"/": {
"post": {
"operationId": "updateAddress",
"summary": "updateAddress",
"servers": [
{
"url": "http://kicsapi.com/",
"description": "server URL"
}
],
"responses": {
"200": {
"description": "The updated address",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Address"
}
}
}
},
"default": {
"description": "Unexpected error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorModel"
}
}
}
}
},
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Address"
},
"examples": {
"Address": {
"$ref": "#/components/schemas/Address"
}
}
}
}
}
}
}
}
}
After
json
{
"openapi": "3.0.0",
"info": {
"title": "Simple API overview",
"version": "1.0.0"
},
"components": {
"securitySchemes": {
"regularSecurity": {
"type": "http",
"scheme": "basic"
}
},
"schemas": {
"ErrorModel": {
"type": "object",
"properties": {
"code": {
"type": "string"
}
}
},
"Address": {
"type": "object",
"properties": {
"street": {
"type": "string"
}
},
"required": [
"street"
]
}
},
"examples": {
"Address": {
"summary": "user address",
"value": {
"street": "my street"
}
}
}
},
"paths": {
"/": {
"post": {
"operationId": "updateAddress",
"summary": "updateAddress",
"servers": [
{
"url": "http://kicsapi.com/",
"description": "server URL"
}
],
"responses": {
"200": {
"description": "The updated address",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Address"
}
}
}
},
"default": {
"description": "Unexpected error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorModel"
}
}
}
}
},
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Address"
},
"examples": {
"Address": {
"$ref": "#/components/examples/Address"
}
}
}
}
}
}
}
}
}