[swagger3] 설정 및 authroize button 활성화하기(Bearer 사용)

버전 2보다 좋은 점은 url에 다음과 같이 되어있을때

http://localhost:9001/swagger-ui/index.html#/1.Login/loginUsingPOST

 

브라우저로 접속하면 해당 api가 바로 펼쳐지면서 이동한다.

(아마 그게 전부... 대신 이 기능을 활용해 문서작성 때 링크달면 용이한거 같다)

 

그럼 설정하는 방법을 시작하겠다.

 

build.gradle 추가

implementation group: 'io.springfox', name: 'springfox-boot-starter', version: '3.0.0'
implementation group: 'io.springfox', name: 'springfox-swagger-ui', version: '3.0.0'

Swagger를 설정하는 Config 파일을 만든다.

@Configuration
@RequiredArgsConstructor
public class SwaggerConfigV3 {
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.OAS_30)
                .securityContexts(Arrays.asList(securityContext()))
                .securitySchemes(Arrays.asList(apiKey()))
                .select()
                .apis(RequestHandlerSelectors.basePackage("[패키지 경로]"))
                .paths(PathSelectors.any())
                .build()
                ;
    }

    private SecurityContext securityContext() {
        return SecurityContext.builder()
            .securityReferences(defaultAuth())
            .build();
    }

    private List<SecurityReference> defaultAuth() {
        AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
        AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
        authorizationScopes[0] = authorizationScope;
        return Arrays.asList(new SecurityReference("Authorization", authorizationScopes));
    }

    private ApiKey apiKey() {
        return new ApiKey("Authorization", "Authorization", "header");
    }
}

 

설정은 이정도만 하면 완료된다.

 

여기서 눈여겨봐야할 것이 securityContext와 apiKey 메서드인데 securityContext는 인증하는 방식을, 그리고 ApiKey는 버튼을 클릭했을때 입력하는 값을 넣는 설정을 하는 것이다.

 

ApiKey는 총 3가지의 것이 확인되었는데 JWT, Bearer, Authorization 등이었다. 그리고 여기서는 Authorization을 설정했다.

 

이제 서버를 켜고 swagger ui를 접속한다.

Authorize 버튼을 클릭하면 다음처럼 화면이 뜬다.

 

Authorize 클릭 후 뜬 화면

 

여기다가 Bearer [accessToken]을 입력하면 된다.

 

그럼 각각 api를 호출하게 될때 다음처럼 header에 토큰값이 포함된다.

curl -X POST "http://localhost:9001/api/test/getMyData" -H "accept: */*" -H "Authorization: Bearer 243b832a-3fe3-44e1-9446-c766a6aaa" -d ""

 

처음 설정할때 apiKey에서 설정한 Authorization이 헤더에 들어간 것을 확인할 수 있다.

 

여기까지가 설정을 완료하는 방법이고 아래부터는 추가 테스트다.

 

그럼 JWT로 변경하면 어떻게 될까?

한번 다음처럼 설정해보겠다

 

...
    private List<SecurityReference> defaultAuth() {
        AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
        AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
        authorizationScopes[0] = authorizationScope;
        return Arrays.asList(new SecurityReference("JWT", authorizationScopes));
    }

    private ApiKey apiKey() {
        return new ApiKey("JWT", "Authorization", "header");
    }
...

 

서버를 새로 띄우고 Authorize 버튼을 클릭하면 다음처럼 텍스트가 변경된 것을 확인할 수 있다.

 

그럼 이전처럼 Bearer [accessToken]을 입력해서 호출하면 어떻게 될까?

curl -X POST "http://localhost:9001/api/test/getMyData" -H "accept: */*" -H "JWT: Bearer 243b832a-3fe3-44e1-9446-c766a6aaa" -d ""

 

이렇게 호출이 되면서 header에 JWT라고 들어간다.

Bearer 로 등록할 경우 Header에 "Bearer: Bearer xxxx" 방식으로 들어가게 된다. 즉 잘못된 설정처럼 된다.

 

 

끝.