전역 인증 요구사항이 없는 OpenAPI 문서

설명

최상위 security가 없으면 API 전체에 적용할 기본 인증 요구사항이 선언되지 않습니다. 개별 작업에서 인증을 지정할 수 있으므로 전역 설정의 부재만으로 인증 누락이라고 볼 수는 없습니다.

잠재적 영향

공통 인증 요구사항을 빠뜨리면 이를 상속해야 할 작업이 명세상 인증을 요구하지 않게 될 수 있습니다. 클라이언트와 서버의 정책이 어긋날 수 있습니다.

해결 방법

공통 정책이 있다면 전역 security를 정의하세요. 작업별로 관리하는 경우 인증이 필요한 모든 작업의 설정을 확인하세요. 참조하는 방식은 OpenAPI 3.0의 components.securitySchemes 또는 2.0의 securityDefinitions에 정의하고 서버에서도 적용하세요.

예시

예시는 기본 인증 요구사항과 이에 대응하는 petstore_auth 정의를 추가합니다. OAuth2 URL은 예시이므로 실제 제공자의 주소로 바꾸세요.

변경 전

json

{
  "openapi": "3.0.0",
  "info": {
    "title": "Simple API overview",
    "version": "1.0.0"
  },
  "paths": {
    "/": {
      "get": {
        "responses": {
          "200": {
            "description": "ok"
          }
        }
      }
    }
  }
}

변경 후

json

{
  "openapi": "3.0.0",
  "info": {
    "title": "Simple API overview",
    "version": "1.0.0"
  },
  "paths": {
    "/": {
      "get": {
        "responses": {
          "200": {
            "description": "ok"
          }
        }
      }
    }
  },
  "security": [
    {
      "petstore_auth": [
        "write:pets",
        "read:pets"
      ]
    }
  ],
  "components": {
    "securitySchemes": {
      "petstore_auth": {
        "type": "oauth2",
        "flows": {
          "authorizationCode": {
            "authorizationUrl": "https://example.com/oauth/authorize",
            "tokenUrl": "https://example.com/oauth/token",
            "scopes": {
              "write:pets": "modify pets in your account",
              "read:pets": "read your pets"
            }
          }
        }
      }
    }
  }
}