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

1. 前言

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

2. Swagger2 中添加 JWT

我们先来回顾在​Swagger2​中是如何添加​JWT​的。在​Swagger2​中我们声明​​Docket​​​Bean 时利用全局参数注入一个​​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​同样也是在声明​​Docket​​Bean 中注入，如下：

@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​进行了分享，作为两种经常在项目中使用的工具，我们不需要知道具体的原理，只知道如何来简化我们的使用和开发即可。今天的分享就到这里，我是​码农小胖哥​，多多关注，多多鼓励，我会分享更多有用的原创编程干货。

​​​​