説明
/users/{id}と/users/{ids}のように構造が同じで変数名だけが異なるパスは、同じURLパターンを表します。OpenAPI 3.0ではこの重複は許可されず、文書とルーティングの対応も不明確になる場合があります。
想定される影響
文書、テスト、SDKが操作を取り違えたり、実際のサーバールーティングと異なるパスを生成したりする可能性があります。
対処方法
同じリソースの異なるメソッドは、一つのパスの下にまとめてください。実際に別のリソースならパス構造を区別し、実装とクライアントも合わせて変更してください。各変数に対応する必須のpathパラメーターを定義してください。
例
OpenAPI 3.0のパス構造を比較する抜粋です。infoと各変数に必要なpathパラメーター定義は省略しています。
変更前
yaml
openapi: 3.0.0
paths:
"/users/{id}":
get:
responses:
"200":
description: OK
"/users/{ids}":
get:
responses:
"200":
description: OK
変更後
yaml
openapi: 3.0.0
paths:
"/users/{id}":
get:
responses:
"200":
description: OK
"/user-groups/{id}":
get:
responses:
"200":
description: OK
変更前は変数名だけが異なり、同じパターンです。変更後はusersとuser-groupsを区別します。実際のAPIでも二つのリソースを区別する場合にだけ、この変更を適用してください。