如何在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,在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
的配置。效果以及流程如下:
我们可以看到请求时会携带一个Bearer Token:
感觉Swagger3中设置JWT比Swagger2中要麻烦一些,不过能用就行。
4. 总结
今天对Swagger2和Swagger3中设置JWT Token进行了分享,作为两种经常在项目中使用的工具,我们不需要知道具体的原理,只知道如何来简化我们的使用和开发即可。今天的分享就到这里,我是码农小胖哥,多多关注,多多鼓励,我会分享更多有用的原创编程干货。
评论系统未开启,无法评论!