Description
If a GET operation does not describe its successful status codes and results, callers must guess the normal outcome. A default response can cover errors and other responses without individual definitions, so it may leave the success contract unclear.
Potential impact
Clients and tests may expect different status codes or data formats for a normal response.
Remediation
Define the success codes actually returned, such as 200 for a typical retrieval. If other successful codes are used, such as 206 for partial content, document their meaning and response format too.
Examples
This OpenAPI 2.0 excerpt adds 200 for a successful retrieval. The response body schema is omitted from this example.
Before
json
{
"swagger": "2.0",
"paths": {
"/item": {
"get": {
"operationId": "getItem",
"summary": "Get item",
"responses": {
"default": {
"description": "Error"
}
}
}
}
}
}
After
json
{
"swagger": "2.0",
"paths": {
"/item": {
"get": {
"operationId": "getItem",
"summary": "Get item",
"responses": {
"200": {
"description": "Success"
},
"default": {
"description": "Error"
}
}
}
}
}
}