설명
경로 파라미터는 URL 경로의 일부이므로 항상 필수 값입니다. in: path인 파라미터에 required: true가 없거나 false로 설정되어 있으면 OpenAPI 3.0 및 2.0의 요구사항에 맞지 않습니다.
잠재적 영향
- API 문서가 경로 파라미터를 선택값처럼 보여 잘못된 요청을 유도할 수 있습니다.
- 코드 생성기나 검증 도구가 정의를 거부하거나 서버와 다른 요청 형식을 만들 수 있습니다.
해결 방법
in: path인 모든 파라미터에 required: true를 명시하세요. 파라미터 이름을 경로의 자리표시자와 일치시키고, 실제 서버가 요구하는 형식도 함께 확인하세요.
예시
OpenAPI 3.0의 경로 파라미터 발췌입니다. 전체 문서에 필요한 info와 작업의 응답 정의는 생략했습니다.
변경 전
json
{
"openapi": "3.0.0",
"paths": {
"/users/{id}": {
"get": {
"parameters": [
{
"name": "id",
"in": "path",
"required": false,
"schema": {
"type": "integer"
}
}
]
}
}
}
}
변경 후
json
{
"openapi": "3.0.0",
"paths": {
"/users/{id}": {
"get": {
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "integer"
}
}
]
}
}
}
}
변경 전에는 id가 선택 사항처럼 선언되어 있습니다. 변경 후에는 required: true로 /users/{id}의 값이 필수임을 명확히 합니다.