정의되지 않은 전역 보안 스킴 참조

설명

OpenAPI 3.0의 전역 security에서 사용한 이름은 components.securitySchemes에 정의되어 있어야 합니다. 이름이 일치하지 않으면 API 사용자가 필요한 인증 방식을 확인하기 어렵습니다.

잠재적 영향

문서 도구나 클라이언트 생성기가 인증 설정을 해석하지 못할 수 있습니다. 문서의 참조 오류만으로 실제 서버의 인증이 꺼졌다고 판단할 수는 없습니다.

해결 방법

참조한 이름과 같은 보안 스킴을 정의하고 실제 인증 방식에 맞춰 설정하세요. OAuth2와 OpenID Connect의 범위 목록을 확인하고, 다른 인증 유형은 빈 배열을 사용하세요. 서버의 인증 적용도 별도로 확인하세요.

예시

전역 petstore_auth 참조에 정의를 추가하는 예시입니다. 포함된 implicit 흐름과 HTTP 인증 주소는 과거 형식이며 운영 권장 구성이 아닙니다. 새 OAuth2 구성에는 HTTPS와 인증 코드 흐름 및 PKCE를 검토하세요.

변경 전

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"
                            }
                          ]
                        }
                      ]
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "security": [
    {
      "petstore_auth": [
        "write:pets",
        "read:pets"
      ]
    }
  ]
}

변경 후

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"
                            }
                          ]
                        }
                      ]
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "security": [
    {
      "petstore_auth": [
        "write:pets",
        "read:pets"
      ]
    }
  ],
  "components": {
    "securitySchemes": {
      "regularSecurity": {
        "type": "http",
        "scheme": "basic"
      },
      "petstore_auth": {
        "type": "oauth2",
        "flows": {
          "implicit": {
            "scopes": {
              "write:pets": "modify pets in your account",
              "read:pets": "read your pets"
            },
            "authorizationUrl": "http://example.org/api/oauth/dialog"
          }
        }
      }
    }
  }
}

변경 후에는 petstore_auth 정의를 찾을 수 있습니다. 별도로 정의된 regularSecurity는 이 security 항목에서 선택되지 않으며, 문서 수정만으로 서버에 인증이 적용되지는 않습니다.