설명
타입 구분자 속성을 문자열로 정의하면 스키마 이름이나 매핑 키와 일관되게 비교하기 쉽습니다. 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을 문자열로 정의합니다. 실제 전송 값도 이 타입과 스키마 매핑에 맞춰야 하며, 타입 선언 변경만으로 데이터가 변환되지는 않습니다.