説明
パスパラメーターは URL パスの一部を構成するため、常に必須です。in: path のパラメーターで required: true を省略したり、false に設定したりすると、OpenAPI 3.0 と 2.0 の要件を満たしません。
想定される影響
- ドキュメントでパスの値が任意と表示され、誤ったリクエストにつながる可能性があります。
- コード生成ツールや検証ツールが定義を拒否したり、サーバーの仕様と異なるリクエストを生成したりする場合があります。
対処方法
すべての in: path パラメーターに required: true を指定してください。名前をパスのプレースホルダーと一致させ、実際のサーバーが要求する形式も確認してください。
例
OpenAPI 3.0 のパスパラメーターの抜粋です。完全な文書に必要な info と操作のレスポンス定義は省略しています。
変更前
json
{
"openapi": "3.0.0",
"paths": {
"/users/{id}": {
"get": {
"parameters": [
{
"name": "id",
"in": "path",
"required": false,
"schema": {
"type": "integer"
}
}
]
}
}
}
}
変更後
json
{
"openapi": "3.0.0",
"paths": {
"/users/{id}": {
"get": {
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "integer"
}
}
]
}
}
}
}
変更前は id を任意として宣言しています。変更後は required: true により、/users/{id} の値が必須であることを明示します。