Description
Without a documented success response for DELETE, callers may be unable to distinguish completed deletion from acceptance for processing. A default response covers status codes not defined individually; it is not reserved for errors.
Potential impact
Clients or automated tests may misinterpret a successful outcome.
Remediation
Document the actual behavior: 200 for completed deletion with a response body, 202 when processing is not yet complete, or 204 for completion without a body. Describe each outcome and any necessary response schema.
Examples
This OpenAPI 3.0 excerpt adds a 204 response for completed deletion without a response body.
Before
json
{
"openapi": "3.0.0",
"paths": {
"/item": {
"delete": {
"operationId": "deleteItem",
"summary": "Delete item",
"responses": {
"default": {
"description": "Error"
}
}
}
}
}
}
After
json
{
"openapi": "3.0.0",
"paths": {
"/item": {
"delete": {
"operationId": "deleteItem",
"summary": "Delete item",
"responses": {
"204": {
"description": "Item deleted successfully"
},
"default": {
"description": "Error"
}
}
}
}
}
}