logo头像

From zero to HERO

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

通过Swagger3Docket提供的securitySchemessecurityReferences方法进行JWT的配置。效果以及流程如下:

Swagger3中jwt使用流程

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

Swagger3中携带jwt

感觉Swagger3中设置JWTSwagger2中要麻烦一些,不过能用就行。

4. 总结

今天对Swagger2Swagger3中设置JWT Token进行了分享,作为两种经常在项目中使用的工具,我们不需要知道具体的原理,只知道如何来简化我们的使用和开发即可。今天的分享就到这里,我是码农小胖哥,多多关注,多多鼓励,我会分享更多有用的原创编程干货。

评论系统未开启,无法评论!