説明
共通の responses に定義したレスポンスは、操作から参照して再利用します。未使用の定義があるだけで仕様が不正になるわけではありませんが、実際のレスポンス契約が分かりにくくなる可能性があります。
想定される影響
実際に返されるレスポンスが分かりにくくなり、不要な定義まで保守することになります。
対処方法
必要なレスポンスを、操作の適切なステータスコードから参照してください。他の文書での使用も確認し、不要になった共通レスポンスだけを削除してください。
例
次の POST の例では、未使用の IllegalInput と GeneralError を削除し、参照されている Success を残しています。
変更前
json
{
"swagger": "2.0",
"info": {
"title": "Simple API Overview",
"version": "1.0.0"
},
"paths": {
"/": {
"post": {
"operationId": "listVersionsv2",
"summary": "List API versions",
"responses": {
"200": {
"$ref": "#/responses/Success"
}
},
"parameters": [
{
"name": "limit2",
"in": "body",
"description": "max records to return",
"required": true,
"schema": {
"type": "string"
}
}
]
}
}
},
"responses": {
"Success": {
"description": "200 response"
},
"IllegalInput": {
"description": "Illegal input for operation."
},
"GeneralError": {
"description": "General Error"
}
}
}
変更後
json
{
"swagger": "2.0",
"info": {
"title": "Simple API Overview",
"version": "1.0.0"
},
"paths": {
"/": {
"post": {
"operationId": "listVersionsv2",
"summary": "List API versions",
"responses": {
"200": {
"$ref": "#/responses/Success"
}
},
"parameters": [
{
"name": "limit2",
"in": "body",
"description": "max records to return",
"required": true,
"schema": {
"type": "string"
}
}
]
}
}
},
"responses": {
"Success": {
"description": "200 response"
}
}
}