존재하지 않는 OpenAPI 3.0 파라미터 참조

설명

OpenAPI 3.0에서는 components.parameters의 파라미터 정의를 여러 작업에서 $ref로 재사용할 수 있습니다. 존재하지 않는 파라미터를 참조하면 입력 위치, 자료형 또는 필수 여부가 문서에서 제대로 설명되지 않을 수 있습니다.

잠재적 영향

API 사용자가 필요한 파라미터를 빠뜨리거나 잘못된 형식으로 전달할 수 있습니다.
문서 검증과 클라이언트 생성이 참조 오류로 실패할 수 있습니다.

해결 방법

파라미터 $ref가 올바른 Parameter 객체를 가리키는지 확인하세요. 로컬 참조는 components.parameters의 이름과 정확히 맞추고, 이름을 바꿨다면 사용하는 모든 참조도 갱신하세요. 수정 후 참조와 입력 정의를 검증하세요.

예시

첫 예제는 정의되지 않은 wrongParameter를 사용합니다.

변경 전

json

{
  "openapi": "3.0.0",
  "info": {
    "title": "Simple API Overview",
    "version": "1.0.0"
  },
  "paths": {
    "/": {
      "get": {
        "operationId": "listVersionsv2",
        "summary": "List API versions",
        "responses": {
          "200": {
            "description": "Success"
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/wrongParameter"
          }
        ]
      }
    }
  },
  "components": {
    "parameters": {
      "limitParam": {
        "name": "limit",
        "in": "query",
        "description": "max records to return",
        "required": true,
        "schema": {
          "type": "integer"
        }
      }
    }
  }
}

변경 후

json

{
  "openapi": "3.0.0",
  "info": {
    "title": "Simple API Overview",
    "version": "1.0.0"
  },
  "paths": {
    "/": {
      "get": {
        "operationId": "listVersionsv2",
        "summary": "List API versions",
        "responses": {
          "200": {
            "description": "Success"
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/limitParam"
          }
        ]
      }
    }
  },
  "components": {
    "parameters": {
      "limitParam": {
        "name": "limit",
        "in": "query",
        "description": "max records to return",
        "required": true,
        "schema": {
          "type": "integer"
        }
      }
    }
  }
}

변경 후에는 limitParam을 참조합니다. 이 정의는 limit라는 필수 정수 쿼리 파라미터를 설명하며, 실제 서버의 입력 검증도 이 계약과 일치해야 합니다.