説明
OpenAPI 3.0とSwagger 2.0では、一つのパラメーター一覧内のnameとinの組み合わせは一意である必要があります。一覧内の重複は解釈を妨げますが、再利用定義のマップで別のキーが同じ組み合わせを定義すること自体は禁止されていません。操作単位の定義で、同じ組み合わせのパス単位の定義を上書きすることもできます。
想定される影響
同じ一覧内の重複は検証や生成エラーにつながる場合があります。一方、有効な再利用定義を不要に変更すると、利用者のパラメーター契約を壊す可能性があります。
対処方法
参照を解決したうえで、各パスや操作のparameters一覧に同じ組み合わせの重複がないか確認してください。意図した操作単位の上書きは維持してください。実際に別の入力が必要な場合だけ名前を変え、クライアントとサーバーの契約も更新してください。
例
OpenAPI 3.0の再利用パラメーター構成要素だけを示す抜粋です。パスや操作の実際の使用一覧とinfoは省略しています。
変更前
json
{
"openapi": "3.0.0",
"components": {
"parameters": {
"limitParam": {
"name": "limit",
"in": "query",
"schema": {
"type": "integer"
}
},
"otherLimitParam": {
"name": "limit",
"in": "query",
"schema": {
"type": "integer"
}
}
}
}
}
変更後
json
{
"openapi": "3.0.0",
"components": {
"parameters": {
"limitParam": {
"name": "limit",
"in": "query",
"schema": {
"type": "integer"
}
},
"offsetParam": {
"name": "offset",
"in": "query",
"schema": {
"type": "integer"
}
}
}
}
}
変更前の二つの構成要素がlimit/queryを定義するだけでは、重複使用の誤りになりません。変更後は別のoffset入力を定義するため、APIが実際に対応する場合だけ適用してください。同じリクエストの一覧での使用方法が重要です。