説明
POST はリソースの作成や処理の依頼など、さまざまな用途で使われます。成功レスポンスが文書にないと、呼び出し側は作成の完了と処理の受け付けを区別しにくくなります。
想定される影響
クライアントが処理中の依頼を完了したものとして扱ったり、リソースの作成結果を誤って処理したりする可能性があります。
対処方法
作成完了の 201、処理完了前の受け付けを示す 202 など、実際の結果に合うコードを文書化してください。202 は最終的な成功を保証しません。レスポンスデータや、その後の状態確認方法も必要に応じて説明してください。
例
次のOpenAPI 3.0の抜粋では、新しい項目の作成成功を示す 201 を追加しています。
変更前
json
{
"openapi": "3.0.0",
"paths": {
"/item": {
"post": {
"operationId": "createItem",
"summary": "Create item",
"responses": {
"default": {
"description": "Error"
}
}
}
}
}
}
変更後
json
{
"openapi": "3.0.0",
"paths": {
"/item": {
"post": {
"operationId": "createItem",
"summary": "Create item",
"responses": {
"201": {
"description": "Item created successfully"
},
"default": {
"description": "Error"
}
}
}
}
}
}