説明
型を区別するプロパティーを文字列にすると、スキーマ名やマッピングキーと一貫して比較しやすくなります。OpenAPI 3.0 のマッピングキーは文字列ですが、ツールが応答値を文字列に変換して比較することも認められています。このため、数値のプロパティーが必ず仕様違反になるわけではありません。未確認の変換への依存は互換性の問題につながります。
想定される影響
サーバーとクライアントで値の比較方法が違うと、異なる派生型を選んだり、型の識別に失敗したりする可能性があります。
対処方法
実際の値とスキーマのマッピングを確認し、可能なら一貫した文字列の仕様を使ってください。既存の数値を文字列へ変える場合はサーバーとクライアントを併せて調整してください。OpenAPI 2.0 の値は、definitions 内の該当するモデル名を表す必要があります。
例
OpenAPI 3.0 のプロパティー型の比較です。派生スキーマ、多態性のための合成、info、paths は省略しています。変更前の数値型は、値の対応付けとツールの変換サポートを併せて確認する必要があります。
変更前
json
{
"openapi": "3.0.0",
"components": {
"schemas": {
"GeneralError": {
"type": "object",
"discriminator": {
"propertyName": "petType"
},
"properties": {
"petType": {
"type": "integer"
}
},
"required": [
"petType"
]
}
}
}
}
変更後
json
{
"openapi": "3.0.0",
"components": {
"schemas": {
"GeneralError": {
"type": "object",
"discriminator": {
"propertyName": "petType"
},
"properties": {
"petType": {
"type": "string"
}
},
"required": [
"petType"
]
}
}
}
}
変更後は petType を文字列にしています。実際に送る値も型とスキーマのマッピングに合わせる必要があり、宣言の変更だけでデータは変換されません。