説明
PUT は対象リソースの作成や置換に使われます。成功レスポンスが文書にないと、呼び出し側は新規作成と既存リソースの更新を区別しにくくなります。
想定される影響
クライアントやテストが、サーバーでリソースが作成されたのか更新されたのかを誤って解釈する可能性があります。
対処方法
新規作成の 201、既存リソースの更新後に本文を返さない場合の 204、本文を返す場合の 200 など、実際の動作に合うレスポンスを定義してください。本文のスキーマは、本文を返すレスポンスにだけ追加してください。
例
次のOpenAPI 3.0の抜粋では、新規作成の 201 と、本文を返さない既存項目の更新の 204 を区別しています。
変更前
json
{
"openapi": "3.0.0",
"paths": {
"/item": {
"put": {
"operationId": "updateItem",
"summary": "Update item",
"responses": {
"default": {
"description": "Error"
}
}
}
}
}
}
変更後
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"
}
}
}
}
}
}