説明
OpenAPI 3.0 では、空配列の意味はフィールドによって異なります。enum: [] には許容値がありませんが、操作の security: [] は全体のセキュリティ要件を解除する有効な宣言です。配列が空という理由だけで任意の値を入れてはいけません。
想定される影響
- 値が必要な配列を空にすると、検証やクライアント生成に支障が生じる場合があります。
- 意図的な空の値と記載漏れを混同すると、文書の認証要件やデータ契約を誤って変更する可能性があります。
対処方法
フィールドの用途と OpenAPI 3.0 での意味を確認してください。値が必要な配列には実際の動作を反映した項目を追加し、意図した空配列は維持してください。認証の宣言を変える場合は、実際のアクセス方針とサーバー側の認証処理も確認してください。
例
最初の例は状態の応答の enum に許容値を指定していません。
変更前
json
{
"openapi": "3.0.0",
"info": {"title": "Status API", "version": "1.0.0"},
"paths": {
"/status": {
"get": {
"responses": {
"200": {
"description": "Current status",
"content": {
"application/json": {
"schema": {"type": "string", "enum": []}
}
}
}
}
}
}
}
}
変更後
json
{
"openapi": "3.0.0",
"info": {"title": "Status API", "version": "1.0.0"},
"paths": {
"/status": {
"get": {
"responses": {
"200": {
"description": "Current status",
"content": {
"application/json": {
"schema": {"type": "string", "enum": ["ready", "busy"]}
}
}
}
}
}
}
}
}
変更後は実際の応答契約に合う状態の値を列挙しています。これは enum の修正であり、すべての空配列を埋めるという意味ではありません。