如何在Swagger2或Swagger3中增加Json Web Token

1. 前言

Swagger 3.0已经发布有一段时间了，作为一个非常有用的文档工具已经越来越多的项目在使用它。而JWT也是目前前后端分离最常用的安全技术。那么如何在Swagger 3.0 中添加JWT Token呢？今天胖哥就分享一下这个知识点。

2. Swagger2 中添加 JWT

我们先来回顾在Swagger2中是如何添加JWT的。在Swagger2中我们声明DocketBean 时利用全局参数注入一个Authorization请求头：

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();
    }
 

效果如下，你只需要填充一个可用的Jwt Token即可。

swagger2中注入jwt请求头

但是这种方式只能适用于 Swagger2，在 Swagger3 中并不凑效。

3. Swagger3 中添加 JWT

那么Swagger3中应该如何做呢？Swagger3同样也是在声明DocketBean 中注入，如下：

    @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();
    }

通过Swagger3中Docket提供的securitySchemes和securityReferences方法进行JWT的配置。效果以及流程如下：

Swagger3中jwt使用流程

我们可以看到请求时会携带一个Bearer Token:

Swagger3中携带jwt

感觉Swagger3中设置JWT比Swagger2中要麻烦一些，不过能用就行。

4. 总结

今天对Swagger2和Swagger3中设置JWT Token进行了分享，作为两种经常在项目中使用的工具，我们不需要知道具体的原理，只知道如何来简化我们的使用和开发即可。