如何通過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的鍵值對即可。