Description
An OpenAPI operation’s responses should describe its actual normal outcomes and known errors. Missing normal outcomes can leave consumers unsure what to expect. The absence of a 2xx entry alone does not make the document invalid; consider intended behavior such as redirects.
Potential impact
Clients or tests may treat a normal response as an error or fail to handle a required response body.
Remediation
Define status codes, descriptions and required headers or bodies that match actual behavior. Do not add codes such as 200, 201 or 204 merely by convention. Review OpenAPI 3.0 2XX range responses and coverage through default, using forms supported by the specification version.
Examples
These OpenAPI 3.0 excerpts show responses only and omit info. 300 is a valid HTTP status code, so determine whether it represents the intended outcome.
Before
{
"openapi": "3.0.0",
"paths": {
"/": {
"get": {
"responses": {
"300": {
"description": "Redirect"
}
}
}
}
}
}
After
{
"openapi": "3.0.0",
"paths": {
"/": {
"get": {
"responses": {
"200": {
"description": "OK"
}
}
}
}
}
}
The after example defines 200 on the assumption that the operation actually returns an ordinary successful response. If the server returns a redirect, changing only the documentation to 200 would misrepresent the contract.