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/...

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

相关推荐
MadPrinter26 分钟前
SpringBoot学习日记 Day11:博客系统核心功能深度开发
java·spring boot·后端·学习·spring·mybatis
dasseinzumtode26 分钟前
nestJS 使用ExcelJS 实现数据的excel导出功能
前端·后端·node.js
淦出一番成就29 分钟前
Java反序列化接收多种格式日期-JsonDeserialize
java·后端
Java中文社群31 分钟前
Hutool被卖半年多了,现状是逆袭还是沉寂?
java·后端
程序员蜗牛1 小时前
9个Spring Boot参数验证高阶技巧,第8,9个代码量直接减半!
后端
yeyong1 小时前
咨询kimi关于设计日志告警功能,还是有启发的
后端
库森学长1 小时前
2025年,你不能错过Spring AI,那个汲取了LangChain灵感的家伙!
后端·openai·ai编程
Java水解2 小时前
Spring Boot 启动流程详解
spring boot·后端
学历真的很重要2 小时前
Claude Code Windows 原生版安装指南
人工智能·windows·后端·语言模型·面试·go
转转技术团队2 小时前
让AI成为你的编程助手:如何高效使用Cursor
后端·cursor