【技术派后端篇】深度剖析 Knife4j：从概述到整合及功能优势
1 Knif4j概述
Knife4j 是一款基于 Swagger 的开源文档管理工具，主要用于生成和管理 API 文档。Knife4j的前身是swagger-bootstrap-ui，是springfox-swagger-ui的增强UI实现。改良后的Knife4j更加小巧、轻量，并且功能更加强大。它不仅在界面上更加优雅、炫酷，还提供了许多增强功能：
- 前后端分离：后端Java代码和前端UI模块分离，使得在微服务场景下更加灵活。
- Markdown支持：在API文档中使用Markdown语法，使文档更具可读性和易于维护。
- 离线文档导出：支持将API文档导出为离线的HTML、PDF或Markdown文件，方便分享。
- 多环境支持：支持在不同的环境（如开发、测试、生产等）中使用不同的API文档配置。
- 动态参数：允许用户在运行时修改API请求的参数，提高测试的灵活性。
以下是Knife4j 的官方地址:
- 官方文档: https://doc.xiaominfo.com/
- 码云地址: https://gitee.com/xiaoym/knife4j
- 示例地址: https://gitee.com/xiaoym/swagger-bootstrap-ui-demo
2 整合Knife4j
2.1 第一步：添加Knife4j依赖
首先，在项目的pom.xml文件中添加Knife4j的依赖。由于Knife4j的starter已经包含了Swagger所需的springfox-boot-starter，因此不需要再单独引入Swagger的依赖。
<dependency><groupId>com.github.xiaoymin</groupId><artifactId>knife4j-spring-boot-starter</artifactId><version>2.0.9</version>
</dependency>
2.2 第二步：配置Knife4j
有两种方式可以配置Knife4j：
- 创建Java配置类：创建一个Java配置类（例如
Knife4jConfig.java），并使用@EnableKnife4j注解启用Knife4j。
@Configuration
@EnableOpenApi
public class SwaggerConfig {@Beanpublic Docket docket() {Docket docket = new Docket(DocumentationType.OAS_30).apiInfo(apiInfo()).enable(true).select()//apis： 添加swagger接口提取范围.apis(RequestHandlerSelectors.basePackage("www.paicoding.controller")).paths(PathSelectors.any()).build();return docket;}private ApiInfo apiInfo() {return new ApiInfoBuilder().title("技术派").description("一个基于 Spring Boot、MyBatis-Plus、MySQL、Redis、ElasticSearch、MongoDB、Docker、RabbitMQ 等技术栈实现的社区系统，采用主流的互联网技术架构、全新的UI设计、支持一键源码部署，拥有完整的文章&教程发布/搜索/评论/统计流程等，代码完全开源，没有任何二次封装，是一个非常适合二次开发/实战的现代化社区项目👍 。").contact(new Contact("沉默王二", "https://paicoding.com","www.qing_gee@163.com")).version("v1.0").build();}
}
- 通过application.yml文件配置：在
application.yml文件中设置属性来启用Knife4j。自2.0.6版本后，只需配置knife4j.enable=true即可。
knife4j:enable: trueopenapi:title: API文档的标题description: API文档的详细描述version: 1.0.0contact:name: 作者名url: 作者网站email: 作者邮箱license: Apache 2.0license-url: http://www.apache.org/licenses/LICENSE-2.0.htmlgroup:admin:group-name: 后台接口分组api-rule: packageapi-rule-resources: com.example.admin.controllerfront:group-name: 前台接口分组api-rule: packageapi-rule-resources: com.example.front.controller
逐个解释这些属性的作用：
knife4j.enable：设置为true以启用Knife4j。knife4j.openapi：包含API文档的基本元数据信息，如标题、描述、版本等。title: API 文档的标题。description: API 文档的详细描述。version: API 文档的版本号。concat: API 文档的作者信息。包括作者名、网站和 GitHub 仓库。license: API 文档的许可证类型。license-url: API 文档许可证的链接。email: API 文档作者的联系邮箱。
knife4j.group：定义API分组，支持按包名扫描API接口。group-name: 分组名称。api-rule: 分组规则，这里使用的是包规则。api-rule-resources: 指定包名，Knife4j 将扫描此包下的所有 API 接口并将它们添加到此分组。
2.3 第三步：添加接口注解
在测试类中使用@ApiOperation、@ApiParam、@ApiModel等注解来描述API操作、参数和数据模型。
- @ApiOperation：用于描述一个具体的API操作。通常用于标注在Controller类的方法上。
- value：API 操作的简短描述，会显示在 API 文档中。
- notes：API 操作的详细描述，会显示在 API 文档中。
- tags：API 操作的标签，用于对 API 进行分类和分组。
@ApiOperation(value = "获取用户信息", notes = "根据用户ID获取用户详细信息")
@GetMapping("/user/{id}")
public User getUserById(@PathVariable Long id) {// 业务逻辑
}
- @ApiParam：用于描述API操作的参数。通常用于标注在Controller类的方法参数上。
- name：参数名称。
- value：参数描述。
- required：指示参数是否是必需的，默认为 false。
- defaultValue：参数的默认值。
- allowableValues：允许的参数值范围。
@ApiOperation(value = "更新用户信息")
@PutMapping("/user")
public User updateUser(@ApiParam(name = "user", value = "用户信息", required = true) @RequestBody User user) {// 业务逻辑
}
- @ApiModel：用于描述一个API操作返回的数据模型或请求数据模型。通常用于标注在实体类或DTO类上。
- value：模型名称。
- description：模型描述。
@ApiModel(value = "User", description = "用户信息")
public class User {private Long id;private String name;// 其他字段和方法
}
2.4 第四步：运行项目并查看API文档
启动项目后，在浏览器地址栏输入http://localhost:8080/doc.html即可查看API文档。左侧菜单展示了文档目录，找到之前添加的测试接口。点击调试选项卡，然后点击发送，就可以直接测试接口并查看返回的响应结果。
通过以上步骤，技术派团队成功整合了Knife4j，极大地提升了API文档的生成和测试体验。Knife4j不仅提供了丰富的功能，还优化了UI界面，使得API文档更具可读性和易用性。
3 Knife4j的优点
Knife4j在Swagger的基础上增加了许多实用功能，优化了UI界面，使得API文档更具可读性和易用性。以下是Knife4j的一些主要功能特点：
3.1 生产环境屏蔽
在生产环境下，为了安全考虑，通常需要屏蔽Swagger的相关资源。Knife4j提供了一个简单的配置选项来实现这一点。只需在application.yml文件中添加以下配置：
knife4j:production: true
采坑提示：配置中至少需要有一个knife4j.setting选项。例如：
knife4j:setting:language: zh-CN
否则会直接报错。
3.2 访问页面加权控制
默认情况下，所有用户都可以无限制访问doc.html，即Knife4j的主页。如果需要增加权限控制，可以在application.yml文件中添加Basic认证功能：
knife4j:basic:enable: trueusername: adminpassword: 123456
配置后，用户在访问API文档时需要输入用户名和密码进行登录。
3.3 支持afterScript
针对JWT类型的接口，调用登录接口后，每个接口请求时需要带上Token参数。Knife4j支持通过脚本动态赋值全局token参数，省去手动复制粘贴的麻烦。
关于AfterScript更详细的使用方法及介绍,请参考文档
3.4 支持全局参数
当某些请求需要全局参数时，这个功能非常实用。可以在左侧菜单的“文档管理”中找到该功能。Knife4j支持header和query两种方式的全局参数配置。
3.5 支持离线文档
Knife4j支持将API文档导出为离线文档，支持的格式包括markdown、HTML、Word等。这对于需要分享文档或在没有网络连接的情况下查看文档非常有用。
3.6 支持JSON折叠
Swagger不支持JSON折叠，当返回的信息非常多时，界面会显得非常臃肿。Knife4j则不同，可以对返回的JSON节点进行折叠，使得界面更加简洁和易于阅读。
3.7 支持搜索API接口
Swagger没有搜索功能，当需要测试的接口非常多时，查找某个特定接口会非常麻烦。Knife4j在文档的右上角提供了文档搜索功能，输入要查询的关键字，即可快速检索筛选接口。目前支持搜索接口的地址、名称和描述。
4 思维导图
5 参考链接
- 技术派API文档之Knife4j
- 项目仓库（GitHub）
- 项目仓库（码云）