Description
Responses to HEAD, and responses with status 204 or 304, have no body under HTTP semantics. Defining a body schema for them conflicts with the actual response contract.
Potential impact
Clients or generated SDKs may try to parse a nonexistent body, or tests may expect an incorrect result.
Remediation
Remove the body definition from these responses: content in OpenAPI 3.0 or the response schema in 2.0. Keep the description and relevant header information.
Examples
This OpenAPI 3.0 excerpt removes content from a 204 response. The referenced ApiVersion definition is omitted from the example.
Before
json
{
"openapi": "3.0.0",
"paths": {
"/": {
"delete": {
"responses": {
"204": {
"description": "has content",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiVersion"
}
}
}
}
}
}
}
}
}
After
json
{
"openapi": "3.0.0",
"paths": {
"/": {
"delete": {
"responses": {
"204": {
"description": "no content"
}
}
}
}
}
}