Description
PUT is used to create or replace the target resource. Without documented success responses, callers may be unable to distinguish creation from an update to an existing resource.
Potential impact
Clients and tests may misinterpret whether the server created or updated the resource.
Remediation
Define responses matching the implementation, such as 201 for creation, 204 for an existing-resource update without a body, or 200 when returning a body. Add a body schema only for responses that return one.
Examples
This OpenAPI 3.0 excerpt distinguishes 201 for a new item from 204 for updating an existing item without a response body.
Before
json
{
"openapi": "3.0.0",
"paths": {
"/item": {
"put": {
"operationId": "updateItem",
"summary": "Update item",
"responses": {
"default": {
"description": "Error"
}
}
}
}
}
}
After
json
{
"openapi": "3.0.0",
"paths": {
"/item": {
"put": {
"operationId": "updateItem",
"summary": "Update item",
"responses": {
"201": {
"description": "Item created successfully"
},
"204": {
"description": "Item updated successfully"
},
"default": {
"description": "Error"
}
}
}
}
}
}