説明
allowEmptyValue は空の値の送信を許可するオプションであり、すべてのパラメーター位置には適用できません。OpenAPI 3.0 では query のみで有効で、使用は推奨されていません。OpenAPI 2.0 では query と formData に使用できます。パラメーター自体の必須指定は、required で別途行います。
想定される影響
- クライアントとサーバーで空の値の扱いが食い違う可能性があります。
- 未対応の位置にあるオプションがツールで拒否または無視され、連携エラーにつながる場合があります。
対処方法
仕様のバージョンとパラメーターの位置を確認し、未対応の allowEmptyValue を削除してください。空の値が必要なら、実際の入力位置、型、シリアライズ方法を併せて確認してください。このオプションのためだけにパス入力をクエリ入力へ移さないでください。
例
OpenAPI 3.0 の抜粋で、info と操作のレスポンス定義は省略しています。変更前の in: path に allowEmptyValue は使用できません。
変更前
json
{
"openapi": "3.0.0",
"paths": {
"/users/{id}": {
"get": {
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"allowEmptyValue": true,
"schema": {
"type": "integer"
}
}
]
}
}
}
}
変更後
json
{
"openapi": "3.0.0",
"paths": {
"/users": {
"get": {
"parameters": [
{
"name": "id",
"in": "query",
"allowEmptyValue": true,
"schema": {
"type": "integer"
}
}
]
}
}
}
}
変更後は /users のクエリ入力へ API 仕様を変えています。これが意図した API である場合に限って適切な比較であり、空の値の処理とツールの対応を確認する必要があります。元のパス仕様を維持する場合は、パスパラメーターから未対応のオプションだけを削除してください。