Description
Without a defined response body structure, clients may not know how to handle the returned data. A bodyless response needs no body schema; use the actual API contract to determine whether a body is present.
Potential impact
Clients may fail to parse responses or use incorrect SDK models, and compatibility problems caused by response changes may be harder to detect.
Remediation
To specify a response body's structure in OpenAPI 3.0, define the media type and schema under content. In OpenAPI 2.0, use the response's schema and applicable produces. Keep these definitions consistent with the actual returned data.
Examples
The example describes an OpenAPI 3.0 JSON response using the shared ApiVersion schema. The referenced definition is omitted from this excerpt.
Before
json
{
"openapi": "3.0.0",
"paths": {
"/": {
"get": {
"responses": {
"200": {
"description": "200 response"
}
}
}
}
}
}
After
json
{
"openapi": "3.0.0",
"paths": {
"/": {
"get": {
"responses": {
"200": {
"description": "200 response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiVersion"
}
}
}
}
}
}
}
}
}