1. Preface

Swagger 3.0 has been released for some time now, and has been used by more and more projects as a very useful documentation tool. And JWT is also the most commonly used security technology for front-end and back-end separation. So how do you add JWT Token to Swagger 3.0?

2. Adding JWTs in Swagger2

Let’s first review how JWT was added in Swagger2. In Swagger2 we declare the Docket bean with a global parameter to inject an Authorization request header.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33

private List<Parameter> jwtToken() {

        String jwt = "Bearer {jwt}";

        ParameterBuilder tokenPar = new ParameterBuilder();
        List<Parameter> pars = new ArrayList<>();
        // 声明 key
        tokenPar.name("Authorization")
                // 文字说明
                .description("jwt令牌")
                // 类型为字符串
                .modelRef(new ModelRef("string"))
                // 参数形式为 header 参数
                .parameterType("header")
                // 默认值
                .defaultValue(jwt)
                // 是否必须
                .required(false);
        pars.add(tokenPar.build());
        return pars;
    }

   @Bean
    public Docket api() {

        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .globalOperationParameters(jwtToken())
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any())
                .build();
    }

The effect is as follows, you just need to populate an available Jwt Token and you’re done.

swgger2

But this approach only works for Swagger2 and doesn’t work in Swagger3.

3. Adding JWT in Swagger3

So how should I do it in Swagger3? Swagger3 is also injected in the declaration Docket bean, as follows.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22

    @Bean
    public Docket api() {

        return new Docket(DocumentationType.OAS_30)
                .apiInfo(apiInfo())
                .securitySchemes(Collections.singletonList(HttpAuthenticationScheme.JWT_BEARER_BUILDER
//                        显示用
                        .name("JWT")
                        .build()))
                .securityContexts(Collections.singletonList(SecurityContext.builder()
                        .securityReferences(Collections.singletonList(SecurityReference.builder()
                                .scopes(new AuthorizationScope[0])
                                .reference("JWT")
                                .build()))
                        // 声明作用域
                        .operationSelector(o -> o.requestMappingPattern().matches("/.*"))
                        .build()))
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any())
                .build();
    }

The configuration of JWT is done through the securitySchemes and securityReferences methods provided by Docket in Swagger3. The result and the flow are as follows.

swagger

We can see that the request will submit a Bearer Token :

swagger

It feels a bit more complicated to set up JWT in Swagger3 than in Swagger2, but it works just fine.

4. Summary

As two tools that are often used in projects, we don’t need to know the exact principle, just how to simplify our use and development.

Reference https://felord.cn/swagger-jwt.html