开发喵星球

Knife4j 是一个基于 Swagger 的增强型 API 文档生成工具，旨在为 Java 开发者提供更直观、更便捷的接口文档管理和展示体验。通过它，开发者可以更轻松地浏览、理解和维护 API 的定义、参数说明、以及返回结果等细节。下面介绍如何在 若依微服务架构 中集成 Knife4j 以增强 Swagger 文档功能。

1. 在 pom.xml 中添加 Knife4j 全局版本号与依赖

首先，需要在项目根目录的 pom.xml 文件中为 knife4j 定义全局版本号。在 properties 节点下添加以下配置：

<knife4j.version>3.0.3</knife4j.version>

然后，在 dependencyManagement 中引入 knife4j 的相关依赖：

<!-- 引入 Knife4j 依赖 -->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-ui</artifactId>
    <version>{knife4j.version}</version>
</dependency>
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <version>{knife4j.version}</version>
</dependency>

2. 在 ruoyi-gateway 模块中添加 Knife4j 依赖

接下来，在 ruoyi-gateway 模块的 pom.xml 文件中，添加如下 Knife4j 依赖：

<!-- Knife4j 依赖 -->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-ui</artifactId>
</dependency>
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
</dependency>

3. 在 ruoyi-common-swagger 模块中引入 Knife4j 依赖

同样地，在 ruoyi-common-swagger 模块中添加如下依赖：

<!-- Knife4j 依赖 -->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
</dependency>

4. 修改 SwaggerProvider.java 类

在 ruoyi-gateway 模块中的 SwaggerProvider.java 类上，添加 @Primary 注解，以确保该类的优先加载：

这样做的目的是优先使用此类的 Swagger 配置，确保接口文档在网关层正常展示。

5. 更新菜单配置

进入系统管理后台，在“菜单管理” -> “系统工具” -> “系统接口”路径下，将路由地址修改为：

http://localhost:8080/doc.html

该配置确保在访问系统接口文档时，能够正确跳转到 Knife4j 增强版 Swagger 文档页面。

完成集成

至此，若依微服务项目已经成功集成了 Knife4j，实现了更为直观的接口文档展示。访问 http://localhost:8080/doc.html 即可查看增强版的 API 文档管理界面，如下图所示：

通过集成 Knife4j，开发者可以更方便地管理、测试和维护项目的 API 接口，极大提升了接口文档的可读性与可维护性。