설명
/users/{id}와 /users/{ids}처럼 구조는 같고 변수 이름만 다른 경로는 같은 URL 패턴을 나타냅니다. OpenAPI 3.0은 이러한 중복을 허용하지 않으며, 문서와 라우팅의 대응도 불분명해질 수 있습니다.
잠재적 영향
문서·테스트·SDK가 어느 작업을 가리키는지 혼동하거나 실제 서버 라우팅과 다른 경로를 생성할 수 있습니다.
해결 방법
같은 리소스의 여러 메서드는 하나의 경로 아래에 모으세요. 실제로 다른 리소스라면 경로 구조를 구분하고 구현·클라이언트도 함께 맞추세요. 각 경로 변수에 맞는 필수 path 파라미터를 정의하세요.
예시
OpenAPI 3.0 경로 구조를 비교하는 발췌입니다. info와 각 변수에 필요한 path 파라미터 정의는 생략했습니다.
변경 전
yaml
openapi: 3.0.0
paths:
"/users/{id}":
get:
responses:
"200":
description: OK
"/users/{ids}":
get:
responses:
"200":
description: OK
변경 후
yaml
openapi: 3.0.0
paths:
"/users/{id}":
get:
responses:
"200":
description: OK
"/user-groups/{id}":
get:
responses:
"200":
description: OK
변경 전은 변수 이름만 달라 같은 패턴입니다. 변경 후는 users와 user-groups를 구분합니다. 실제 API도 두 리소스를 구분하는 경우에만 이런 변경을 적용하세요.