security requirement에 잘못된 스코프를 사용하는 경우

설명

OpenAPI 3.0에서 스코프는 oauth2 또는 openIdConnect 보안 방식에만 사용할 수 있습니다. apiKey나 http 방식에 스코프를 지정하면 문서의 인증 요구사항이 해당 방식과 맞지 않게 됩니다.

잠재적 영향

검증 도구가 문서를 오류로 처리하거나 API 사용자가 지원하지 않는 스코프를 요청할 수 있습니다.

해결 방법

apiKey와 http 방식의 보안 요구사항에는 빈 배열 []을 사용하십시오. oauth2 또는 openIdConnect에는 실제로 필요한 스코프를 지정하고 인증 제공자의 설정과 일치시키십시오.

예시

예시는 api_key의 스코프를 제거하고 OAuth2의 스코프는 유지합니다. 별도 배열 항목은 대안이므로 두 인증 방식을 모두 요구하지는 않습니다. OAuth2 인가 코드 흐름은 PKCE와 함께 사용하십시오.

변경 전

json

{
  "openapi": "3.0.0",
  "info": {
    "title": "Simple API Overview",
    "version": "1.0.0"
  },
  "security": [
    {
      "api_key": [
        "write:api",
        "read:api"
      ]
    },
    {
      "petstore_auth": [
        "write:pets",
        "read:pets"
      ]
    }
  ],
  "paths": {},
  "components": {
    "securitySchemes": {
      "api_key": {
        "type": "apiKey",
        "name": "api_key",
        "in": "header"
      },
      "petstore_auth": {
        "type": "oauth2",
        "flows": {
          "authorizationCode": {
            "authorizationUrl": "https://example.org/api/oauth/dialog",
            "tokenUrl": "https://example.org/api/oauth/token",
            "scopes": {
              "write:pets": "modify pets in your account",
              "read:pets": "read your pets"
            }
          }
        }
      }
    }
  }
}

변경 후