如何通过knife4j设置全局token

本文将介绍如何在使用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的键值对即可。