説明
数値スキーマの format は、integer や number の表現方法をさらに具体化します。省略可能な項目なので、未指定であること自体は誤りではありません。ただし、特定の表現方法が必要なAPIでは、明示することで実装間の解釈の違いを減らせます。
想定される影響
クライアントとサーバーが異なる数値のサイズや精度を選ぶと、値の切り捨てやシリアライズ結果の違いが生じる可能性があります。
対処方法
表現方法が重要な場合は、integer に int32 や int64、number に float や double など、適切な format を指定してください。ツールの対応状況と生成される型を確認し、業務上の値の範囲は minimum と maximum で別途定義してください。
例
次のOpenAPI 3.0の抜粋では、0から50までの整数という既存の制約を維持しながら、int32 の表現情報を追加しています。
変更前
json
{
"openapi": "3.0.0",
"components": {
"schemas": {
"GeneralError": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"minimum": 0,
"maximum": 50
}
}
}
}
}
}
変更後
json
{
"openapi": "3.0.0",
"components": {
"schemas": {
"GeneralError": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"format": "int32",
"minimum": 0,
"maximum": 50
}
}
}
}
}
}