18. knife4j 接口文档

Spring Cloud 微服务系列文章，点击上方合集↑

1. 简介

Knife4j是一款国产开源的API接口文档在线查看工具，它基于Spring Doc构建，提供简单的配置即可自动生成在线文档。Knife4j不仅具备友好的界面，而且使用简单，还提供了增强功能如接口测试和Mock数据生成，可大大提高开发人员的工作效率。

官网定义： Knife4j是一个集Swagger2 和 OpenAPI3 为一体的增强解决方案

官网地址：https://doc.xiaominfo.com（官方文档很齐全）

Knife4j界面鉴赏：https://doc.xiaominfo.com/docs/introduction/ui

2. Spring Boot 集成 Knife4j

2.1 pom.xml

添加knife4j-openapi3-spring-boot-starter依赖。

<dependency>
    <groupId>com.github.xiaoymingroupId>
    <artifactId>knife4j-openapi3-spring-boot-starterartifactId>
    <version>4.3.0version>
dependency>
1
2
3
4
5

2.2 application.properties

注意：

1. com.example.knife4juser要修改成您自己的包路径
2. knife4j.enable生产环境下一定要关闭接口文档

# Swagger UI的访问路径
springdoc.swagger-ui.path=/swagger-ui.html
# 标签的排序方式
springdoc.swagger-ui.tags-sorter=alpha
# 接口的排序方式
springdoc.swagger-ui.operations-sorter=alpha
springdoc.api-docs.path=/v3/api-docs
springdoc.group-configs[0].group=default
springdoc.group-configs[0].paths-to-match=/**
# 指定需要扫描的包路径
springdoc.group-configs[0].packages-to-scan=com.example.knife4juser
# 是否启用Knife4j
knife4j.enable=true
knife4j.setting.language=zh_cn
1
2
3
4
5
6
7
8
9
10
11
12
13
14

2.3 访问

地址加/doc.html访问文档：http://localhost:8310/doc.html

可以对接口进行在线测试

3. Gateway 网关聚合

如果每个微服务都按照上述配置方式（将Knife4j配置放在配置中心公共配置文件中），那么单独访问每个微服务的接口文档会变得很麻烦。这时候可以通过网关Gateway来聚合所有服务的接口文档，使得我们只需通过访问网关一次即可查看并管理整个系统的API接口。通过这种方式，我们可以方便地统一访问和管理所有服务的接口文档，提高开发者的效率和系统的可维护性。

3.1 pom.xml

Gateway网关添加knife4j-openapi3-spring-boot-starter依赖。

<dependency>
    <groupId>com.github.xiaoymingroupId>
    <artifactId>knife4j-gateway-spring-boot-starterartifactId>
    <version>4.3.0version>
dependency>
1
2
3
4
5

3.2 application.properties

Gateway网关的主要配置如下：

• knife4j.gateway.enabled=true：启用Knife4j的网关聚合功能。
• knife4j.gateway.strategy=discover：设置Knife4j的网关扩展功能的策略为服务发现。
• knife4j.gateway.discover.enabled=true：启用Knife4j的服务发现功能。
• knife4j.gateway.discover.version=openapi3：设置Knife4j的服务发现功能的版本为OpenAPI 3.0。
• knife4j.gateway.discover.excluded-services[0]=knife4j-gateway：设置需要排除的微服务，例如这里排除了名为knife4j-gateway的服务，不会被Knife4j的服务发现功能所发现和扩展。

spring.application.name=knife4j-gateway
server.port=10001
# 服务注册与发现
spring.cloud.nacos.discovery.username=nacos
spring.cloud.nacos.discovery.password=nacos
spring.cloud.nacos.discovery.server-addr=http://localhost:8848
# 启用了自动根据服务名建立路由
spring.cloud.gateway.discovery.locator.enabled=true
# knife4j文档
knife4j.gateway.enabled=true
knife4j.gateway.strategy=discover
knife4j.gateway.discover.enabled=true
knife4j.gateway.discover.version=openapi3
# 需要排除的微服务(eg:网关服务) 
knife4j.gateway.discover.excluded-services[0]=knife4j-gateway
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

3.3 访问

通过网关的地址加/doc.html访问文档：http://localhost:10001/doc.html

可以在这里选择切换不同的服务模块。

3.4 设置全局参数

大多数我们请求接口都需要在请求头携带令牌等信息，可以在knife4j设置全局参数，如下：

4 总结

本文介绍了如何在Spring Boot应用中使用Knife4j这一API文档在线查看工具，并通过配置Gateway实现了API接口聚合。

使用Knife4j可以方便地生成API接口文档，提高开发效率以及降低开发成本。而聚合接口可以使得我们可以统一管理不同服务的API文档，便于开发人员查阅和使用。

---

Spring Cloud 微服务系列 完整的代码在仓库的sourcecode/spring-cloud-demo目录下。

gitee(推荐)：https://gitee.com/cunzaizhe/xiaohuge-blog

github：https://github.com/tigerleeli/xiaohuge-blog

关注微信公众号：“小虎哥的技术博客”，让我们一起成为更优秀的程序员❤️！