설명
allowEmptyValue는 비어 있는 값의 전송을 허용하는 옵션이며 모든 파라미터 위치에 적용되지는 않습니다. OpenAPI 3.0에서는 query에만 유효하고 사용을 권장하지 않습니다. OpenAPI 2.0에서는 query와 formData에 사용할 수 있습니다. 파라미터 자체의 필수 여부는 required로 별도 지정합니다.
잠재적 영향
- 클라이언트와 서버가 빈 값 허용 여부를 다르게 해석할 수 있습니다.
- 허용되지 않는 위치의 옵션은 도구에서 거부되거나 무시되어 연동 오류를 일으킬 수 있습니다.
해결 방법
사용하는 버전과 파라미터 위치를 확인하고 허용되지 않는 allowEmptyValue를 제거하세요. 빈 값이 필요한 경우 실제 API의 입력 위치, 타입과 직렬화 방식을 함께 검토하세요. 이 옵션을 쓰기 위해서만 경로 입력을 쿼리 입력으로 옮기지 마세요.
예시
OpenAPI 3.0 발췌이며 info와 작업의 응답 정의는 생략했습니다. 변경 전의 in: path에는 allowEmptyValue를 사용할 수 없습니다.
변경 전
json
{
"openapi": "3.0.0",
"paths": {
"/users/{id}": {
"get": {
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"allowEmptyValue": true,
"schema": {
"type": "integer"
}
}
]
}
}
}
}
변경 후
json
{
"openapi": "3.0.0",
"paths": {
"/users": {
"get": {
"parameters": [
{
"name": "id",
"in": "query",
"allowEmptyValue": true,
"schema": {
"type": "integer"
}
}
]
}
}
}
}
변경 후에는 /users의 쿼리 입력으로 API 계약이 달라집니다. 쿼리 입력이 실제 의도인 경우에만 가능한 비교이며, 빈 값의 처리 방식과 도구 지원을 확인해야 합니다. 기존 경로 계약을 유지하려면 경로 파라미터에서 지원하지 않는 옵션만 제거하세요.