説明
OpenAPIの文書では、操作が実際に返す成功レスポンスと既知のエラーを説明する必要があります。すべての操作で同じステータスコードの一覧が必須になるわけではなく、実際のAPI契約に合わせて定義します。
想定される影響
クライアントやテストがエラーを誤って処理したり、サーバーとは異なるレスポンスを想定したりする可能性があります。
対処方法
各操作で返す可能性のあるステータスコードと意味、ヘッダー、必要な本文スキーマを定義してください。認証失敗、アクセス拒否、リクエスト制限なども、実際にサポートする動作に合わせて説明してください。
例
次のOpenAPI 3.0の抜粋では、PUT の一部のエラーレスポンスと OPTIONS のレスポンスを明示しています。一律に必要なコードの一覧ではなく、PUT の成功レスポンスなどは省略しています。
変更前
json
{
"openapi": "3.0.0",
"paths": {
"/item": {
"put": {
"responses": {
"default": {
"description": "Error"
}
}
},
"options": {
"responses": {
"default": {
"description": "Error"
}
}
}
}
}
}
変更後
json
{
"openapi": "3.0.0",
"paths": {
"/item": {
"put": {
"responses": {
"400": { "description": "400 response" },
"404": { "description": "404 response" },
"415": { "description": "415 response" },
"429": { "description": "429 response" },
"500": { "description": "500 response" }
}
},
"options": {
"responses": {
"200": { "description": "200 response" },
"400": { "description": "400 response" },
"429": { "description": "429 response" },
"500": { "description": "500 response" }
}
}
}
}
}