파라미터 값 형식 정의 누락

설명

OpenAPI 3.0의 Parameter Object는 schema 또는 content 중 하나로 값의 타입과 표현 방식을 정의해야 합니다. 둘 다 없으면 경로, 쿼리, 헤더 또는 쿠키 파라미터를 어떤 형식으로 전달해야 하는지 불명확해집니다.

잠재적 영향

클라이언트가 잘못된 타입이나 형식의 값을 전송해 요청이 실패하거나 SDK가 파라미터를 잘못 처리할 수 있습니다.

해결 방법

일반적인 값은 schema로 타입과 제약을 정의하고, 미디어 유형을 지정하는 표현에는 content를 사용하십시오. 두 필드를 함께 지정하지 마십시오. $ref를 사용한다면 참조한 파라미터 정의가 올바른지 확인하십시오.

예시

예시는 /user/{id}의 id를 정수로 정의합니다. 경로 파라미터는 경로의 자리표시자 이름과 일치해야 합니다.

변경 전

json

{
  "openapi": "3.0.0",
  "paths": {
    "/user/{id}": {
      "parameters": [
        {
          "name": "id",
          "in": "path",
          "required": true,
          "description": "ID of the API version"
        }
      ]
    }
  }
}

변경 후

json

{
  "openapi": "3.0.0",
  "paths": {
    "/user/{id}": {
      "parameters": [
        {
          "name": "id",
          "in": "path",
          "required": true,
          "description": "ID of the API version",
          "schema": {
            "type": "integer"
          }
        }
      ]
    }
  }
}