설명
숫자 스키마의 format은 integer나 number를 더 구체적으로 표현합니다. format은 선택 사항이므로 생략 자체가 오류는 아니지만, 특정 표현 방식이 필요한 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
}
}
}
}
}
}