파라미터 식별 조합과 사용 위치 점검

설명

OpenAPI 3.0과 Swagger 2.0에서 한 파라미터 목록 안의 name과 in 조합은 고유해야 합니다. 같은 목록의 중복은 명세 해석을 방해할 수 있지만, 재사용 정의 목록에서 서로 다른 키가 같은 조합을 정의하는 것 자체는 금지되지 않습니다. 작업 수준의 정의는 같은 조합의 경로 수준 정의를 재정의할 수도 있습니다.

잠재적 영향

같은 목록의 중복 정의는 검증이나 코드 생성 오류를 일으킬 수 있습니다. 반대로 유효한 재사용 정의를 불필요하게 바꾸면 소비자의 파라미터 계약이 깨질 수 있습니다.

해결 방법

각 경로·작업의 parameters 목록을 참조 해석 후 확인하고 같은 조합의 중복을 제거하세요. 의도한 작업 수준 재정의는 유지하세요. 실제로 다른 입력이 필요한 경우에만 이름을 바꾸고 클라이언트와 서버의 계약을 함께 갱신하세요.

예시

OpenAPI 3.0의 재사용 파라미터 구성 요소만 보여주는 발췌입니다. 실제 경로·작업의 사용 목록과 info는 생략했습니다.

변경 전

json

{
  "openapi": "3.0.0",
  "components": {
    "parameters": {
      "limitParam": {
        "name": "limit",
        "in": "query",
        "schema": {
          "type": "integer"
        }
      },
      "otherLimitParam": {
        "name": "limit",
        "in": "query",
        "schema": {
          "type": "integer"
        }
      }
    }
  }
}

변경 후

json

{
  "openapi": "3.0.0",
  "components": {
    "parameters": {
      "limitParam": {
        "name": "limit",
        "in": "query",
        "schema": {
          "type": "integer"
        }
      },
      "offsetParam": {
        "name": "offset",
        "in": "query",
        "schema": {
          "type": "integer"
        }
      }
    }
  }
}

변경 전의 두 구성 요소가 같은 limit/query 조합을 정의하는 것만으로는 중복 사용 오류가 아닙니다. 변경 후는 별도의 offset 입력을 정의하므로 실제 API에 그 입력이 있을 때만 적용하세요. 같은 요청 목록에서 어떤 정의를 사용하는지가 중요합니다.