설명
OpenAPI 2.0의 additionalProperties에는 불리언 값이나 스키마를 사용할 수 있습니다. false는 정의하지 않은 속성을 금지하고, true 또는 생략은 허용하며, 스키마는 추가 속성의 값에 제약을 적용합니다. 불리언을 사용했다는 사실만으로 잘못된 명세가 되는 것은 아닙니다.
잠재적 영향
- 허용 범위가 의도보다 넓으면 구현에 따라 예상하지 않은 데이터를 받아들일 수 있습니다.
- 반대로 필요한 확장 속성을 금지하면 정상적인 요청과 호환되지 않을 수 있습니다.
해결 방법
데이터 계약에 따라 additionalProperties를 선택하세요. 추가 속성을 금지하려면 false를 유지하고, 허용하려면 필요한 값의 스키마를 지정하거나 true를 사용하세요. 서버의 실제 입력 검증도 확인하고, 명세만 바꾸어 허용 범위를 불필요하게 넓히지 마세요.
예시
첫 예제는 응답 객체에서 정의하지 않은 속성을 허용하지 않습니다. 다음 예제는 서로 다른 추가 속성 정책을 비교합니다.
변경 전
json
{
"swagger": "2.0",
"info": {
"title": "Simple API Overview",
"version": "1.0.0"
},
"paths": {
"/": {
"get": {
"operationId": "listVersionsv2",
"summary": "List API versions",
"responses": {
"200": {
"description": "200 response",
"schema": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"tag": {
"type": "string"
}
},
"required": [
"name"
],
"additionalProperties": false
}
}
}
}
}
}
}
변경 후
json
{
"swagger": "2.0",
"info": {
"title": "Simple API Overview",
"version": "1.0.0"
},
"paths": {
"/": {
"get": {
"operationId": "listVersionsv2",
"summary": "List API versions",
"responses": {
"200": {
"description": "200 response",
"schema": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"tag": {
"type": "string"
}
},
"required": [
"name"
],
"additionalProperties": {
"$ref": "#/definitions/User"
}
}
}
}
}
}
},
"definitions": {
"User": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"tag": {
"type": "string"
}
},
"required": [
"name"
]
}
}
}
변경 후에는 User 스키마에 맞는 값을 가진 추가 속성을 허용합니다. false를 스키마로 바꾸면 계약의 의미가 달라지므로, 모든 경우에 필요한 수정은 아닙니다.