説明
PATCH はリソースを部分的に変更する操作です。成功レスポンスが文書にないと、呼び出し側は更新が完了したかどうかや、返されたデータの扱いを判断しにくくなります。
想定される影響
クライアントやテストが更新結果を誤って解釈し、サーバーとは異なる状態を表示する可能性があります。
対処方法
実際の更新結果に合う成功コードを定義してください。例えば、結果の本文を返す場合は 200、更新完了後に本文を返さない場合は 204 を使用できます。各結果の意味と必要なデータスキーマを説明してください。
例
次のOpenAPI 3.0の抜粋では、更新が完了し、本文を返さない場合の 204 を追加しています。
変更前
json
{
"openapi": "3.0.0",
"paths": {
"/item": {
"patch": {
"operationId": "updateItem",
"summary": "Updated item",
"responses": {
"default": {
"description": "Error"
}
}
}
}
}
}
変更後
json
{
"openapi": "3.0.0",
"paths": {
"/item": {
"patch": {
"operationId": "updateItem",
"summary": "Update item",
"responses": {
"204": {
"description": "Item updated successfully"
},
"default": {
"description": "Error"
}
}
}
}
}
}