説明
OpenAPI 3.0のオブジェクトスキーマでは、additionalProperties を省略するか true にすると、未定義のプロパティも許可されます。定義済みのフィールドだけを受け入れる設計の場合、APIの契約より広い範囲を許可することになります。
想定される影響
サーバーが意図しないリクエストフィールドをそのまま保存・処理すると、想定外の動作につながる可能性があります。レスポンスでは、文書にないフィールドによってクライアントのデータの解釈が異なることもあります。
対処方法
定義済みのフィールドだけを許可する場合は additionalProperties: false を指定し、実際の検証に反映してください。動的なキーが必要なオブジェクトでは追加プロパティを許可し、必要に応じて値のスキーマを定義してください。
例
次のOpenAPI 3.0のレスポンススキーマの抜粋では、id と name 以外のフィールドを拒否するように変更しています。この変更だけで両フィールドが必須になるわけではありません。
変更前
json
{
"openapi": "3.0.0",
"paths": {
"/": {
"get": {
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": { "type": "string" },
"name": { "type": "string" }
},
"additionalProperties": true
}
}
}
}
}
}
}
}
}
変更後
json
{
"openapi": "3.0.0",
"paths": {
"/": {
"get": {
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": { "type": "string" },
"name": { "type": "string" }
},
"additionalProperties": false
}
}
}
}
}
}
}
}
}