springdoc swagger ui에 authorize 사용해 보기

swagger ui에서 api를 테스트하면서 인증을 사용하고 싶은 경우 어떻게 하면 될까?

swagger는 이와 관련하여 securityScheme를 제공한다.

@SecurityScheme annotation을 사용하거나 OpenAPI 설정의 securityScheme 항목을 설정하면 된다.

springdoc 문서에는 OpenAPI 설정에 대한 예시가 있다.
https://springdoc.org/#how-can-i-define-securityscheme

SecuritySchema 설정하기

 @Bean
 public OpenAPI customOpenAPI(@Value("${springdoc.version}") String appVersion) {
  return new OpenAPI()
   .components(new Components().addSecuritySchemes("basicScheme",
   new SecurityScheme().type(SecurityScheme.Type.HTTP).scheme("basic")))
   info(new Info().title("SpringShop API").version(appVersion)
   .license(new License().name("Apache 2.0").url("http://springdoc.org")));
 }

@SecurityScheme를 사용하는 경우 다음과 같이 사용할 수 있다.

@Configuration
@SecurityScheme( 
    name = "securityHeader",  
    type = SecuritySchemeType.APIKEY, 
    in = SecuritySchemeIn.HEADER
)
public class SomeConfigClass {
}

위 두 사용의 예제는 1개의 인증 설정에 대해 보여주었지만 여러 개의 인증에 대해 반복하여 설정할 수도 있다.
@SecurityScheme를 사용한 경우를 예를 들면 다음과 같다.

@SecurityScheme(
    name = "securityHeader",  
    type = SecuritySchemeType.APIKEY, 
    in = SecuritySchemeIn.HEADER
)
@SecurityScheme(
    name = "securityCookie",  
    type = SecuritySchemeType.APIKEY, 
    in = SecuritySchemeIn.COOKIE,
    paramName = "jsessionid" 
)
public class SomeConfigClass {
}

위와 같이 설정하게 되면 openapi 문서에는 securitySchemes 관련 설정 항목이 추가되고 이를 기반으로 swagger ui의 상단에 authorize 버튼이 생성되어 인증 관련 설정을 할 수 있게 된다.

각 API들은 위에서 설정한 여러 인증 들 중 어떤 것을 사용할지 지정할 수 있다.
@Operation의 security 항목으로 설정을 한다.

@Operation(
    security = { @SecurityRequirement(name = "securityCookie") }
    // ... 기타 내용들
)
public SomeDomain someMethod(... someArgument) {
    // ... 
    return someDomain;
}

security 항목이 설정되면 api 항목에 자물쇠 표시가 보이고 이 자물쇠를 클릭하면 해당 API가 사용할 인증에 관련한 설정 항목만 보이게 된다.
관련 설정을 하면 해당 api 요청 시 관련 인증 설정이 같이 추가되어 요청하게 된다.

SecurityScheme 설정 옵션들

인증과 관련하여 openAPI는 다음과 같은 항목들을 정의하고 있다.

SecurirtySchemeType

• apiKey
• http
• openIdConnect
• oauth2

SecuritySchemeIn

• header
• query
• cookie

사용하고자 하는 인증과 설정할 위치를 지정하면 된다.

Cookie 인증 api 테스트 시 문제

내 경우 쿠키를 사용한 apiKey 인증을 사용하였다.
요청 시 쿠키에 설정된 paramName (없으면 name이 기본 설정됨)으로 입력한 쿠키 값을 같이 보내야 하는데 Swagger UI는 브라우저 보안 제한 사항으로 인해 try it out (api를 실제 호출해 보기)에서는 cookie 인증을 지원하지 않고 curl, request url 예제에만 추가해 준다.
https://swagger.io/docs/specification/authentication/cookie-authentication/

Note for Swagger UI and Swagger Editor users: Cookie authentication is currently not supported for "try it out" requests due to browser security restrictions. See this issue for more information. SwaggerHub does not have this limitation.

인증 설정을 하더라도 의도한 대로 인증 쿠키 값을 테스트할 수 없다.

따라서 swagger ui를 통해 쿠키를 사용한 api 호출을 테스트하려면 호출할 api의 도메인에 대해 쿠키를 브라우저에서 따로 생성하여 사용하는 수밖에 없을 것 같다.
swagger ui의 withCredentials 설정을 활성화해 주면 요청에 header cookie 값을 보내게 된다.