설명
OpenAPI 3.0의 객체 스키마는 additionalProperties가 생략되거나 true이면 정의되지 않은 속성도 허용합니다. 정해진 필드만 받아야 하는 객체라면 이 설정이 API 계약보다 넓은 범위를 허용할 수 있습니다.
잠재적 영향
서버가 의도하지 않은 요청 필드를 그대로 저장하거나 처리하면 예상하지 못한 동작이 생길 수 있습니다. 응답에서는 문서에 없는 필드 때문에 클라이언트의 데이터 해석이 달라질 수 있습니다.
해결 방법
정해진 필드만 허용하려면 additionalProperties: false를 지정하고 실제 검증에 반영하세요. 동적 키가 필요한 객체라면 추가 속성을 허용하되, 필요한 경우 그 값의 스키마를 정의하세요.
예시
다음 OpenAPI 3.0 응답 스키마 발췌 예시는 id와 name 이외의 필드를 허용하지 않도록 바꿉니다. 두 필드를 필수로 만드는 변경은 아닙니다.
변경 전
json
{
"openapi": "3.0.0",
"paths": {
"/": {
"get": {
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": { "type": "string" },
"name": { "type": "string" }
},
"additionalProperties": true
}
}
}
}
}
}
}
}
}
변경 후
json
{
"openapi": "3.0.0",
"paths": {
"/": {
"get": {
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": { "type": "string" },
"name": { "type": "string" }
},
"additionalProperties": false
}
}
}
}
}
}
}
}
}