중복된 operationId 사용

설명

operationId는 각 API 작업을 식별하는 값입니다. 정의하는 경우 API 전체에서 고유해야 합니다. 여러 엔드포인트나 메서드에서 같은 값을 사용하면 코드 생성기, SDK와 문서 도구가 작업을 구분하지 못할 수 있습니다.

잠재적 영향

SDK 메서드 이름 충돌이나 잘못된 작업 참조로 인해 생성·연동 오류가 발생할 수 있습니다.

해결 방법

정의한 operationId에 중복이 없는지 확인하고 작업 목적을 반영한 이름을 사용하세요. 이름을 변경하면 이를 참조하는 링크, 생성 클라이언트와 자동화도 함께 갱신하세요.

예시

OpenAPI 3.0 작업 식별자만 비교하는 발췌입니다. 완전한 문서의 info와 각 작업에 필요한 responses는 생략했습니다.

변경 전

json

{
  "openapi": "3.0.0",
  "paths": {
    "/": {
      "get": {
        "operationId": "operation_id"
      },
      "post": {
        "operationId": "operation_id"
      }
    }
  }
}

변경 후

json

{
  "openapi": "3.0.0",
  "paths": {
    "/": {
      "get": {
        "operationId": "listRootResource"
      },
      "post": {
        "operationId": "createRootResource"
      }
    }
  }
}

변경 전은 GET과 POST가 같은 식별자를 사용합니다. 변경 후는 조회와 생성 작업에 서로 다른 이름을 부여합니다. 식별자 변경 자체가 서버의 경로나 동작을 바꾸지는 않습니다.