설명
경로 템플릿의 자리표시자는 {id}처럼 이름이 있어야 합니다. /users/{}처럼 빈 자리표시자를 사용하면 어떤 값을 받는 경로인지 알 수 없고, 도구도 이를 정상적인 경로 파라미터로 처리하기 어렵습니다.
잠재적 영향
- API 경로 의미가 불명확해 문서 해석과 구현이 어긋날 수 있습니다.
- 코드 생성기나 검증 도구가 명세를 오류로 처리할 수 있습니다.
해결 방법
빈 {}를 실제 API에서 사용하는 {id}나 {userId} 같은 이름으로 수정하세요. 같은 이름의 in: path 파라미터를 경로 또는 작업에 정의하고 required: true를 지정하세요.
예시
OpenAPI 3.0 경로 이름의 차이만 보여 주는 발췌입니다. info와 경로 파라미터 선언은 생략했으며, 실제 문서에는 해당 선언을 추가해야 합니다.
변경 전
yaml
openapi: 3.0.0
paths:
/users/{}:
get:
responses:
"200":
description: OK
변경 후
yaml
openapi: 3.0.0
paths:
/users/{id}:
get:
responses:
"200":
description: OK
변경 전에는 자리표시자 이름이 비어 있습니다. 변경 후의 {id}는 이름을 명확히 하지만, 완전한 정의에는 같은 이름의 필수 경로 파라미터도 필요합니다.