Description
OpenAPI 3.0 components.responses holds reusable response definitions. A $ref to a missing response can prevent tools from resolving that status code’s description, headers or body structure.
Potential impact
- API users may misunderstand how to handle an error or success response.
- Reference errors can cause specification validation or code generation to fail.
Remediation
Check that the response $ref points to an existing Response Object. Match local references to components.responses definitions, and review the response description and body schema. Validate the documented status codes and response structures against actual behavior.
Examples
These examples compare references for a 404 response. The first target, NotRight, does not exist.
Before
json
{
"openapi": "3.0.0",
"info": {
"title": "Simple API Overview",
"version": "1.0.0"
},
"paths": {
"/": {
"get": {
"operationId": "listVersionsv2",
"summary": "List API versions",
"responses": {
"404": {
"$ref": "#/components/responses/NotRight"
}
}
}
}
},
"components": {
"schemas": {
"Error": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
}
},
"required": [
"code",
"message"
]
}
},
"responses": {
"NotFound": {
"description": "Resource not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
}
After
json
{
"openapi": "3.0.0",
"info": {
"title": "Simple API Overview",
"version": "1.0.0"
},
"paths": {
"/": {
"get": {
"operationId": "listVersionsv2",
"summary": "List API versions",
"responses": {
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
}
},
"components": {
"schemas": {
"Error": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
}
},
"required": [
"code",
"message"
]
}
},
"responses": {
"NotFound": {
"description": "Resource not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
}
The second example references NotFound, connecting the response description to the Error schema. The schema-level required list makes code and message required fields.