응답 헤더 정의와 HTTP 의미 점검

설명

OpenAPI 3.0의 응답 headers에 정의한 Content-Type은 무시되며, 응답 본문 형식은 content로 표현합니다. Accept나 Authorization이라는 이름만으로 모든 응답 헤더가 일괄적으로 금지되는 것은 아니므로 실제 HTTP 의미와 계약을 확인해야 합니다.

잠재적 영향

본문 형식을 잘못 문서화하거나 표준 헤더를 업무 데이터에 오용하면 생성된 클라이언트와 실제 응답이 어긋날 수 있습니다.

해결 방법

OpenAPI 3.0의 응답 content 또는 Swagger 2.0의 produces로 미디어 타입을 설명하세요. 다른 응답 헤더는 실제 서버가 반환하는 이름과 값의 형식에 맞춰 정의하고, 표준 헤더의 의미를 임의로 바꾸지 마세요.

예시

OpenAPI 3.0에서 Content-Type 헤더 정의와 별도 Pet 헤더를 비교합니다. Pet은 실제 업무 메타데이터가 필요한 경우에만 사용할 예시이며, 본문 형식 헤더를 단순히 바꾼 이름이 아닙니다.

변경 전

json

{
  "openapi": "3.0.0",
  "info": {
    "title": "Simple API Overview",
    "version": "1.0.0"
  },
  "paths": {
    "/": {
      "get": {
        "operationId": "listVersionsv2",
        "summary": "List API versions",
        "responses": {
          "500": {
            "description": "500 response",
            "content": {
              "application/json": {
                "examples": {
                  "foo": {
                    "value": {
                      "versions": [
                        {
                          "status": "CURRENT",
                          "updated": "2011-01-21T11:33:21Z",
                          "id": "v2.0",
                          "links": [
                            {
                              "href": "http://127.0.0.1:8774/v2/",
                              "rel": "self"
                            }
                          ]
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "400 response",
            "headers": {
              "Content-Type": {
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "examples": {
                  "foo": {
                    "value": {
                      "versions": [
                        {
                          "status": "CURRENT",
                          "updated": "2011-01-21T11:33:21Z",
                          "id": "v2.0",
                          "links": [
                            {
                              "href": "http://127.0.0.1:8774/v2/",
                              "rel": "self"
                            }
                          ]
                        }
                      ]
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}

변경 후