説明
OpenAPI 2.0 の additionalProperties には真偽値またはスキーマを使用できます。false は未定義のプロパティを禁止し、true または省略は許可します。スキーマを指定すると追加プロパティの値を制約します。真偽値を使っただけで仕様書が不正になるわけではありません。
想定される影響
- 意図より広く許可すると、実装によっては想定外のデータを受け入れる可能性があります。
- 必要な拡張プロパティを禁止すると、正当な要求と互換性がなくなる可能性があります。
対処方法
データ契約に応じて additionalProperties を選択してください。追加プロパティを禁止する場合は false を維持し、許可する場合は必要な値のスキーマまたは true を指定してください。サーバー側の実際の入力検証も確認し、仕様書の変更で許容範囲を不要に広げないでください。
例
最初の例は、応答オブジェクトの未定義のプロパティを禁止しています。以下は異なる追加プロパティの方針を比較する例です。
変更前
json
{
"swagger": "2.0",
"info": {
"title": "Simple API Overview",
"version": "1.0.0"
},
"paths": {
"/": {
"get": {
"operationId": "listVersionsv2",
"summary": "List API versions",
"responses": {
"200": {
"description": "200 response",
"schema": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"tag": {
"type": "string"
}
},
"required": [
"name"
],
"additionalProperties": false
}
}
}
}
}
}
}
変更後
json
{
"swagger": "2.0",
"info": {
"title": "Simple API Overview",
"version": "1.0.0"
},
"paths": {
"/": {
"get": {
"operationId": "listVersionsv2",
"summary": "List API versions",
"responses": {
"200": {
"description": "200 response",
"schema": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"tag": {
"type": "string"
}
},
"required": [
"name"
],
"additionalProperties": {
"$ref": "#/definitions/User"
}
}
}
}
}
}
},
"definitions": {
"User": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"tag": {
"type": "string"
}
},
"required": [
"name"
]
}
}
}
変更後は、User スキーマに適合する値を持つ追加プロパティを許可します。false をスキーマに置き換えると契約の意味が変わるため、どの場合にも必要な修正ではありません。