本文将介绍如何在使用knife4j作为接口文档管理工具时，通过设置全局token来提高接口文档的安全性。
一、什么是knife4j
Knife4j是一款基于springfox的开源的Swagger接口文档生成工具。它不仅可以将Swagger风格的API文档转换成具有可视化界面的文档，而且可以通过文档管理和测试接口。
二、为什么要设置全局token
在应用程序中，对于一些敏感的API接口，需要进行身份验证。而Swagger2默认情况下不支持token的全局配置，如果我们只是选择在每个API接口请求时单独传递token，则会增加很多重复代码，不便于维护。而通过设置全局token，则可以避免这样的麻烦。
三、如何设置全局token
我们可以通过在Swagger的全局配置中添加一个拦截器，以便在每个请求中都验证用户的token。 token的值可以从项目的配置文件中读取。
1. 新建拦截器
我们可以从Spring的HandlerInterceptor接口开始，新建一个拦截器类TokenInterceptor，然后在preHandle()方法中进行token鉴权校验，如果token认证失败，则抛出异常提示用户。
public class TokenInterceptor extends HandlerInterceptorAdapter {
private final Logger logger = LoggerFactory.getLogger(TokenInterceptor.class);
@Override
public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) throws Exception {
String token = request.getHeader("token");
if (StringUtils.isEmpty(token)) {
logger.warn("Token is empty");
throw new ServiceException(ResponseCode.UNAUTHORIZED);
}
// 鉴权逻辑，如果token不正确，则返回401错误
if (!jwtTokenUtils.validateToken(token)) {
logger.warn("Token is invalid");
throw new ServiceException(ResponseCode.UNAUTHORIZED);
}
// 鉴权通过，则继续执行
return true;
}
}
2. 注册拦截器
在Swagger的全局配置类SwaggerConfiguration中，我们可以通过Swagger2的Bean配置方法添加TokenInterceptor拦截器，如下所示：
@Configuration
@EnableSwagger2
public class SwaggerConfiguration {
@Value("${jwt.secret}")
private String secret;
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.paths(PathSelectors.any())
.build().securitySchemes(Collections.singletonList(securityScheme()));
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("Swagger API")
.description("Swagger API")
.version("1.0")
.build();
}
private SecurityScheme securityScheme() {
return new ApiKey("token", "token", "header");
}
@Override
public void addInterceptors(InterceptorRegistry registry) {
registry.addInterceptor(new TokenInterceptor(secret)).excludePathPatterns("/v2/api-docs/**");
}
}
这里我们还需要定义一个securityScheme来告诉Swagger以何种方式传递token。这里我们使用header的方式传递token。
3. 在应用程序中使用token
在请求Swagger API时，我们需要在请求头中添加带有token的键值对。如果token鉴权失败，则Swagger会响应401错误。
以下是将token添加到请求头中的代码实例：
@RequestMapping(value = "/test", method = RequestMethod.POST)
public Object test(@RequestHeader("token") String token) {
// 处理请求
}
四、总结
通过设置全局token，我们可以更方便地进行API接口的身份验证，提高了应用程序的安全性。在使用Knife4j作为接口文档管理工具时，我们可以通过添加拦截器来验证用户的token，并通过Swagger的全局配置进行注册。在实际应用中，我们只需要在请求头中传递带有token的键值对即可。