본문이 없는 응답에 본문 정의 (OpenAPI 3.0)

설명

HEAD 요청의 응답과 204, 304 응답에는 HTTP 의미상 본문이 없습니다. 이런 응답에 본문 스키마를 정의하면 문서와 실제 응답 계약이 충돌합니다.

잠재적 영향

클라이언트나 생성된 SDK가 존재하지 않는 본문을 파싱하려 하거나 테스트가 잘못된 결과를 기대할 수 있습니다.

해결 방법

이 응답들에서 본문 정의를 제거하세요. OpenAPI 3.0에서는 content, 2.0에서는 응답의 schema가 해당합니다. 설명과 필요한 헤더 정보는 유지하세요.

예시

다음 OpenAPI 3.0 발췌 예시는 204 응답의 content를 제거합니다. 참조된 ApiVersion의 정의는 예시에서 생략했습니다.

변경 전

json

{
  "openapi": "3.0.0",
  "paths": {
    "/": {
      "delete": {
        "responses": {
          "204": {
            "description": "has content",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiVersion"
                }
              }
            }
          }
        }
      }
    }
  }
}

변경 후

json

{
  "openapi": "3.0.0",
  "paths": {
    "/": {
      "delete": {
        "responses": {
          "204": {
            "description": "no content"
          }
        }
      }
    }
  }
}