SpringBoot轻松实现项目集成Knife4j接口文档

Knife4j 介绍

Knife4j 官网

Knife4j是一款基于Swagger生成API文档的增强工具，它简化了开发者构建和管理RESTful API文档的过程。通过自动扫描项目中的接口信息，Knife4j能够生成详细、易读的API文档，无需手动编写和维护。它提供交互式的接口调试页面，方便验证接口正确性，同时支持接口聚合和分组，便于管理大型项目中的接口。此外，Knife4j还支持Markdown文档，以及定制化配置选项，使得API文档更加美观、灵活和易于展示。总体而言，Knife4j是一款功能强大的工具，能够提升API文档质量和开发效率，推动团队协作和沟通。

依赖引入

Knife4j其实就相当Swagger的升级版，相比于比Swagger要好用多了。

<!-- Knife4j -->
<dependency><groupId>com.github.xiaoymin</groupId><artifactId>knife4j-openapi2-spring-boot-starter</artifactId><version>4.0.0</version>
</dependency>

Knife4j 配置类

package com.hsqyz.config.common;import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiKey;
import springfox.documentation.service.AuthorizationScope;
import springfox.documentation.service.SecurityReference;
import springfox.documentation.service.SecurityScheme;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spi.service.contexts.SecurityContext;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2WebMvc;import java.util.ArrayList;
import java.util.List;/*** Knife4j 配置*/
@Configuration
@EnableSwagger2WebMvc // 开启Swagger
public class Knife4jConfiguration {@Bean(value = "defaultApi2")public Docket defaultApi2() {return new Docket(DocumentationType.SWAGGER_2)// 是否启用Swagger.enable(true)// 用来创建该API的基本信息，展示在文档的页面中（自定义展示的信息）.apiInfo(new ApiInfoBuilder().title("API接口文档").description("API接口文档描述").termsOfServiceUrl("http://127.0.0.1:8080/")// 联系方式(这里以本人邮箱为例).contact("1926585708@qq.com").version("1.0.0").build())// 分组名称.groupName("default")// 设置哪些接口暴露给Swagger展示.select()// 这里指定Controller扫描包路径.apis(RequestHandlerSelectors.basePackage("com.hsqyz.controller"))// 路径选择器.paths(PathSelectors.any()).build()/*** 设置安全模式，swagger可以设置访问token*/.securitySchemes(securitySchemes()).securityContexts(securityContexts()).pathMapping("/");}/*** 安全模式，这里指定token通过Authorization头请求头传递*/private List<SecurityScheme> securitySchemes() {List<SecurityScheme> apiKeyList = new ArrayList<SecurityScheme>();apiKeyList.add(new ApiKey("Authorization", "Authorization", "header"));return apiKeyList;}/*** 安全上下文*/private List<SecurityContext> securityContexts() {List<SecurityContext> securityContexts = new ArrayList<>();securityContexts.add(SecurityContext.builder().securityReferences(defaultAuth()).build());return securityContexts;}/*** 默认的安全上引用*/private List<SecurityReference> defaultAuth() {AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];authorizationScopes[0] = authorizationScope;List<SecurityReference> securityReferences = new ArrayList<>();securityReferences.add(new SecurityReference("Authorization", authorizationScopes));return securityReferences;}}

版本说明

如果出现错误：

Failed to start bean 'documentationPluginsBootstrapper'; nested exception is java.lang.NullPointerException

图例问题

这里提供两种修复方案

降低Spring Boot 版本到2.6.x以下版本

比如下面版本组合是兼容的

Spring Boot版本	Swagger 版本
2.5.6	2.9.2

SpringBoot版本不降级解决方案

配置文件中加上：

properties 格式

spring.mvc.pathmatch.matching-strategy=ant_path_matcher

yaml 格式

spring:  mvc:pathmatch:matching-strategy=ant_path_matcher

项目运行后，访问ip+端口号+/doc.html，比如：http://localhost:8080/doc.html

全局参数

在实际项目中访问接口都添加了权限，每次访问都要带一个请求头参数token。全局参数就是为了方便传一个固定的参数。当添加全局参数后，所有的接口都会带上该参数。

这里介绍2种设置全局参数的方法

第一种【编码方式】

使用securitySchemes()和securityContexts()来设置

引用代码

/*** 安全模式，这里指定token通过Authorization头请求头传递*/private List<SecurityScheme> securitySchemes() {List<SecurityScheme> apiKeyList = new ArrayList<SecurityScheme>();apiKeyList.add(new ApiKey("Authorization", "Authorization", "header"));return apiKeyList;}/*** 安全上下文*/private List<SecurityContext> securityContexts() {List<SecurityContext> securityContexts = new ArrayList<>();securityContexts.add(SecurityContext.builder().securityReferences(defaultAuth()).build());return securityContexts;}/*** 默认的安全上引用*/private List<SecurityReference> defaultAuth() {AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];authorizationScopes[0] = authorizationScope;List<SecurityReference> securityReferences = new ArrayList<>();securityReferences.add(new SecurityReference("Authorization", authorizationScopes));return securityReferences;}

效果：菜单上多了一个Authorize，在参数值中添加上信息

刷新一下，再打开接口就会发现多了个请求头部

第二种【手动配置全局参数】

直接在菜单文档管理→全局参数设置，然后添加参数：

添加保存

再打开接口就会发现请求头参数加上了

过滤拦截说明

如果使用了安全相关的框架，例如(SaToken，SpringSecurity、包括手动定义的拦截器与过滤器)，可能会拦截到Knife4j的文档接口，导致文档加载失败，需要手动放行这方面的接口

Apifox 一键导入 knife4j 接口文档

点击导入项目

选择Knife4j，填入地址后进行解析

解析出来的地址就是你的分组接口详细信息地址，点击提交即可

参考文章

Spring Boot项目集成Knife4j接口文档的实例代码
knife4j v2.0 用户指南