説明
OpenAPI 3.0 と 2.0 の各操作には、一つ以上のレスポンス定義を含む空でない responses が必要です。これは、使っていない再利用用の応答マップである components.responses や OpenAPI 2.0 の最上位 responses が空である場合とは異なります。
想定される影響
レスポンスの仕様がないと、利用者が状態コードやデータ形式を把握しにくくなり、SDK 生成や文書に基づく検証が不完全になる可能性があります。
対処方法
各操作の responses に実際に返すレスポンスを一つ以上定義してください。通常の応答と既知のエラーを説明し、適切な場合は default を使ってください。文書を埋めるためだけに、サーバーが返さない 200 レスポンスを作らないでください。
例
OpenAPI 3.0 の操作レスポンスの抜粋です。info は省略しています。変更前の操作の responses: {} には必要な応答定義がありません。
変更前
json
{
"openapi": "3.0.0",
"paths": {
"/": {
"get": {
"responses": {}
}
}
}
}
変更後
json
{
"openapi": "3.0.0",
"paths": {
"/": {
"get": {
"responses": {
"200": {
"description": "OK"
}
}
}
}
}
}
変更後は、実際の通常応答が 200 である場合の定義を示しています。返す本文やエラー応答も実際の仕様に合わせて追加してください。