헤더 값 형식 정의 누락

설명

OpenAPI 3.0의 Header Object는 schema 또는 content 중 하나로 값의 형식을 정의합니다. 둘 다 없으면 클라이언트가 숫자, 문자열 등의 타입과 표현 방식을 정확히 알기 어렵습니다.

잠재적 영향

문서 도구나 SDK가 헤더 타입을 잘못 처리하거나 클라이언트가 값을 잘못 해석할 수 있습니다.

해결 방법

일반적인 헤더 값은 schema에 실제 타입과 필요한 제약을 정의하십시오. 미디어 유형을 지정해 표현할 때는 content를 사용하고 두 방식을 동시에 정의하지 마십시오. 공통 정의를 참조한다면 참조 대상의 형식을 확인하십시오.

예시

예시는 응답 헤더 X-Rate-Limit-Limit의 값을 정수로 정의합니다.

변경 전

json

{
  "openapi": "3.0.0",
  "components": {
    "responses": {
      "ResponseExample": {
        "headers": {
          "X-Rate-Limit-Limit": {
            "description": "The number of allowed requests in the current period"
          }
        }
      }
    }
  }
}

변경 후

json

{
  "openapi": "3.0.0",
  "components": {
    "responses": {
      "ResponseExample": {
        "headers": {
          "X-Rate-Limit-Limit": {
            "description": "The number of allowed requests in the current period",
            "schema": {
              "type": "integer"
            }
          }
        }
      }
    }
  }
}