1.简介

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

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

官网地址： https://doc.xiaominfo.com（官方文档很齐全）
Knife4j界面鉴赏：https://doc.xiaominfo.com/docs/introduction/ui

2, Springboot 集成knife4j

2.1 pom.xml

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

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-openapi3-spring-boot-starter</artifactId>
    <version>4.3.0</version>
</dependency>

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

2.3 访问

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

61a2bf5990a47e88d39a81eb36e37972.png

可以对接口进行在线测试

d6af4349a0420f87e468f7963447a77a.png

3 Gateway 网关聚合

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

3.1 pom.xml

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

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-gateway-spring-boot-starter</artifactId>
    <version>4.3.0</version>
</dependency>

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

3.3 访问

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

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

726eec6829e5919e4352dee7152eb464.png

3.4 设置全局参数

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

41ef146173a30c3bcb21c7373acea3e9.png d8213f4e06eda3b3396d8157dfe4985a.png

4 总结

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

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

a36e6461d926875cd8c46ceb9dcad087.png