잘못된 헤더 객체 참조 (OpenAPI 3.0)

설명

응답 헤더의 $ref는 헤더의 형식과 의미를 정의하는 헤더 객체를 가리켜야 합니다. 응답 객체 등 다른 종류의 정의를 참조하면 해당 헤더를 올바르게 해석할 수 없습니다.

잠재적 영향

헤더 정보가 문서에서 누락되거나 명세 검증과 클라이언트 코드 생성이 실패할 수 있습니다.

해결 방법

공통 헤더는 #/components/headers/...의 올바른 정의를 참조하세요. 외부 파일도 유효한 헤더 객체를 제공하면 사용할 수 있습니다.

예시

다음 예시는 RateLimit의 참조 경로를 responses에서 headers로 수정합니다.

변경 전

json

{
  "openapi": "3.0.0",
  "info": {"title": "Rate Limit API", "version": "1.0.0"},
  "paths": {
    "/status": {
      "get": {
        "responses": {
          "200": {
            "description": "OK",
            "headers": {
              "X-Rate-Limit-Limit": {
                "$ref": "#/components/responses/RateLimit"
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "headers": {
      "RateLimit": {
        "description": "Requests allowed per hour",
        "schema": {"type": "integer"}
      }
    }
  }
}

변경 후

json

{
  "openapi": "3.0.0",
  "info": {"title": "Rate Limit API", "version": "1.0.0"},
  "paths": {
    "/status": {
      "get": {
        "responses": {
          "200": {
            "description": "OK",
            "headers": {
              "X-Rate-Limit-Limit": {
                "$ref": "#/components/headers/RateLimit"
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "headers": {
      "RateLimit": {
        "description": "Requests allowed per hour",
        "schema": {"type": "integer"}
      }
    }
  }
}