Accept 헤더 파라미터 정의 점검

설명

Accept는 클라이언트가 원하는 응답 형식을 전달하는 HTTP 헤더입니다. OpenAPI 3.0에서는 이 이름의 일반 헤더 파라미터 정의를 무시하도록 규정하므로, 응답 미디어 타입으로 계약을 설명해야 합니다.

잠재적 영향

일반 파라미터로 정의한 값이 문서 도구에 반영되지 않거나, 업무 입력과 응답 형식 협상을 혼동할 수 있습니다.

해결 방법

응답 형식은 OpenAPI 3.0의 응답 content 또는 Swagger 2.0의 produces로 설명하세요. 실제 별도 입력은 의미에 맞는 파라미터로 정의하고 서버와 클라이언트의 계약을 함께 확인하세요. HTTP Accept 헤더 자체를 사용하지 말라는 뜻은 아닙니다.

예시

OpenAPI 3.0에서 ID 입력의 위치와 이름을 비교하는 발췌입니다. /users/{id}의 별도 경로 파라미터 정의는 생략했습니다.

변경 전

json

{
  "openapi": "3.0.0",
  "info": {
    "title": "Simple API overview",
    "version": "1.0.0"
  },
  "paths": {
    "/": {
      "get": {
        "operationId": "listVersionsv2",
        "summary": "List API versions",
        "responses": {
          "200": {
            "description": "200 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"
                            }
                          ]
                        }
                      ]
                    }
                  }
                }
              }
            }
          }
        }
      },
      "parameters": [
        {
          "name": "Accept",
          "in": "header",
          "description": "ID of the API the version",
          "required": true,
          "schema": {
            "type": "integer"
          }
        }
      ]
    },
    "/users/{id}": {
      "get": {
        "parameters": [
          {
            "in": "header",
            "name": "Accept",
            "required": true,
            "description": "The user ID",
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          }
        ],
        "responses": {
          "200": {
            "description": "200 response"
          }
        }
      }
    }
  }
}

변경 후