Authorization 헤더 파라미터 정의 점검

설명

Authorization은 HTTP 인증 정보를 전달하는 헤더입니다. OpenAPI 3.0에서는 이 이름을 가진 일반 헤더 파라미터를 무시하므로, 인증 계약은 보안 스킴과 security로 설명해야 합니다.

잠재적 영향

인증 입력이 문서 도구에 나타나지 않거나 사용자가 일반 업무 입력과 혼동할 수 있습니다. 문서만 수정한다고 서버에 인증이 적용되지는 않습니다.

해결 방법

OpenAPI 3.0에서는 components.securitySchemes, Swagger 2.0에서는 securityDefinitions에 인증 방식을 정의하고 security에서 참조하세요. 인증과 무관한 입력이라면 별도 이름을 쓰고 실제 요청 처리와 일치시켜야 합니다.

예시

Authorization을 ID 입력으로 잘못 사용한 예시입니다. /users/{id}에 필요한 별도 경로 파라미터 정의는 생략한 OpenAPI 3.0 발췌입니다.

변경 전

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": "Authorization",
          "in": "header",
          "description": "ID of the API the version",
          "required": true,
          "schema": {
            "type": "integer"
          }
        }
      ]
    },
    "/users/{id}": {
      "get": {
        "parameters": [
          {
            "in": "header",
            "name": "Authorization",
            "required": true,
            "description": "The user ID",
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          }
        ],
        "responses": {
          "200": {
            "description": "200 response"
          }
        }
      }
    }
  }
}

변경 후

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": "id",
          "in": "query",
          "description": "ID of the API the version",
          "required": true,
          "schema": {
            "type": "integer"
          }
        }
      ]
    },
    "/users/{id}": {
      "get": {
        "parameters": [
          {
            "in": "header",
            "name": "id",
            "required": true,
            "description": "The user ID",
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          }
        ],
        "responses": {
          "200": {
            "description": "200 response"
          }
        }
      }
    }
  }
}

변경 후 ID 입력은 인증 헤더와 분리됩니다. 별도 인증이 필요한 API라면 보안 스킴과 서버의 인증 처리도 구성해야 합니다.