18. knife4j 接口文档

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

1. 简介

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

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

官网地址:doc.xiaominfo.com(官方文档很齐全)

Knife4j界面鉴赏:doc.xiaominfo.com/docs/introd...

2. Spring Boot 集成 Knife4j

2.1 pom.xml

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

xml 复制代码
<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生产环境下一定要关闭接口文档
properties 复制代码
# 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

可以对接口进行在线测试

3. Gateway 网关聚合

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

3.1 pom.xml

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

xml 复制代码
<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的服务发现功能所发现和扩展。
properties 复制代码
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

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

3.4 设置全局参数

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

4 总结

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

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


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

gitee(推荐):gitee.com/cunzaizhe/x...

github:github.com/tigerleeli/...

关注微信公众号:"小虎哥的技术博客",让我们一起成为更优秀的程序员❤️!

相关推荐
世界哪有真情13 分钟前
用虚拟IP扩容端口池:解决高并发WebSocket端口耗尽问题
前端·后端·websocket
知其然亦知其所以然21 分钟前
JVM社招面试题:队列和栈是什么?有什么区别?我在面试现场讲了个故事…
java·后端·面试
武子康25 分钟前
大数据-30 ZooKeeper Java-API 监听节点 创建、删除节点
大数据·后端·zookeeper
知了一笑25 分钟前
SpringBoot3集成多款主流大模型
spring boot·后端·openai
wmze27 分钟前
InnoDB存储引擎--索引与锁
后端
星辰大海的精灵30 分钟前
如何确保全球数据管道中的跨时区数据完整性和一致性
java·后端·架构
调试人生的显微镜32 分钟前
iOS App首次启动请求异常调试:一次冷启动链路抓包与初始化流程修复
后端
AI小智35 分钟前
Context Engineering:AI 工程的下一个前沿阵地?
后端
paopaokaka_luck35 分钟前
基于SpringBoot+Vue的酒类仓储管理系统
数据库·vue.js·spring boot·后端·小程序
梦兮林夕37 分钟前
02 gRPC 语法及类型介绍
后端·go·grpc