Description
An OpenAPI description should document an operation’s actual successful responses and known errors. The same status-code list is not mandatory for every operation; definitions should reflect the actual API contract.
Potential impact
Clients and tests may mishandle errors or expect responses that differ from the server’s behavior.
Remediation
Define the status codes, meaning, headers, and necessary body schemas for responses each operation can return. Describe authentication failure, access denial, and request limits according to the behavior actually supported.
Examples
This OpenAPI 3.0 excerpt lists selected PUT error responses and OPTIONS responses. It is not a universally required code list; other responses, including successful PUT outcomes, are omitted from this example.
Before
json
{
"openapi": "3.0.0",
"paths": {
"/item": {
"put": {
"responses": {
"default": {
"description": "Error"
}
}
},
"options": {
"responses": {
"default": {
"description": "Error"
}
}
}
}
}
}
After
json
{
"openapi": "3.0.0",
"paths": {
"/item": {
"put": {
"responses": {
"400": { "description": "400 response" },
"404": { "description": "404 response" },
"415": { "description": "415 response" },
"429": { "description": "429 response" },
"500": { "description": "500 response" }
}
},
"options": {
"responses": {
"200": { "description": "200 response" },
"400": { "description": "400 response" },
"429": { "description": "429 response" },
"500": { "description": "500 response" }
}
}
}
}
}