当前位置：首页 > backend >正文

Spring Boot整合knife4j实战

backend 2025/8/11 15:59:16

本文为个人学习笔记整理，仅供交流参考，非专业教学资料，内容请自行甄别

文章目录

前言
一、Spring Boot整合knife4j
二、前端项目整合@umijs/openapi

前言

knife4j是一款基于 Swagger 的 API 文档工具，主要用于生成、展示和调试后端 API 文档，提供了更友好的 UI 和交互体验（相比原生 Swagger UI），方便前后端协作时查看接口定义。并且可以配合前端的@umijs/openapi，自动生成前端接口请求代码（包括 TypeScript 类型定义、API 调用函数等），简化前端对接后端接口的流程，避免手动编写重复的请求代码。

一、Spring Boot整合knife4j

首先需要引入依赖，根据Spring Boot2 和Spring Boot合理选择，我的版本是Spring Boot 2：

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

然后在配置文件中进行设置：

# 接口文档相关配置（knife4j是基于Swagger的增强工具）
knife4j:enable: true  # 是否启用knife4j功能，true表示启用，会生成API文档并提供UI界面openapi:  # OpenAPI规范相关配置（Swagger/OpenAPI的核心配置）title: 接口文档  # 接口文档的标题，会显示在文档UI的顶部version: 1.0  # 接口文档的版本号，用于标识API的迭代版本group:  # 接口分组配置（支持多组API文档，适用于大型项目分模块管理）default:  # 默认分组名称（可自定义，如"user-api"、"order-api"）api-rule: package  # 接口扫描规则：按包路径扫描（指定包下的接口会被纳入当前分组）api-rule-resources:  # 具体的扫描资源路径（配合api-rule使用）- org.ragdollcat.first.controller  # 需要扫描的控制器包路径，该包下的所有接口会被包含到当前分组文档中

启动项目，访问http://ip:port/doc.html：
在这里插入图片描述
主页展示基本信息

在这里插入图片描述

具体的接口，以及对应字段的含义，可以通过注解的方式定义

下面这几个注解是定义在接口及对应的方法上的。

@Api：注释具体的Controller接口的作用。
@ApiOperation：接口中方法的作用，以及方法的描述。
@ApiResponses：定义返回值的含义，可以有多个@ApiResponse组成。
@ApiParam：定义方法参数的含义

@RestController
@RequestMapping("/")
@Api(tags = "心跳检测controller")
public class MainController {/*** 服务健康检查接口* 用于监控系统或第三方服务检测当前服务是否正常运行* 通常被用于K8s、Nacos等服务注册中心的健康探针** @return BaseResponse<String> 统一响应体*         - 成功时返回状态码200和消息"ok"*         - 若服务异常，会被全局异常处理器捕获并返回对应错误信息*/@GetMapping("/health")@ApiOperation(value = "服务健康检查", notes = "检查服务是否正常运行，正常返回'ok'")@ApiResponses({@ApiResponse(code = 0, message  = "服务正常运行"),@ApiResponse(code = 500, message  = "服务内部错误")})public BaseResponse<String> health() {// 实际生产环境中可添加更复杂的检查逻辑// 例如：数据库连接检测、缓存服务连通性等return ResultUtils.success("ok");}
}

下面这几个注解是定义在实体类或具体字段上的。

@ApiModel：实体类的作用
@ApiModelProperty：字段的含义

@Data
@ApiModel(description = "系统统一返回类")
public class BaseResponse<T> implements Serializable {@ApiModelProperty(value = "状态码")private int code;@ApiModelProperty(value = "具体数据")private T data;@ApiModelProperty(value = "状态信息")private String message;public BaseResponse(int code, T data, String message) {this.code = code;this.data = data;this.message = message;}public BaseResponse(int code, T data) {this(code, data, "");}public BaseResponse(ErrorCode errorCode) {this(errorCode.getCode(), null, errorCode.getMessage());}
}

二、前端项目整合@umijs/openapi

如果使用的是npm管理工具，则使用如下命令导入：

npm i --save-dev @umijs/openapi

导入成功后，在package.json中可以看到对应的依赖：
在这里插入图片描述
在项目的根目录下创建openapi.config.js文件，@umijs/openapi 只需要后端提供符合 OpenAPI 规范的接口文档（无论是通过 Swagger、knife4j 还是其他工具生成的），就能完成代码生成工作。而knife4j是后端接口文档的增强工具，它本质上还是基于 OpenAPI 规范输出接口文档，因此可以作为 @umijs/openapi 的 “数据源” 之一，但并非唯一选择。

import { generateService } from '@umijs/openapi'//生成接口代码的配置
generateService({requestLibPath: "import request from '@/request'",// 后端提供的标准的 OpenAPI 文档的路径schemaPath: 'http://localhost:9080/api/v2/api-docs',// 生成的请求文件存放的路径serversPath: './src',
})

定义脚本进行测试
在这里插入图片描述
运行后，找到生成的对应controller的mainController.ts文件，发现controller中相应方法的前端请求代码已经生成，并且通过export关键字导出，可以在其他模块中引用

在App.vue中导入，启动项目查看效果：

<script setup lang="ts">
import { healthUsingGet } from '@/api/mainController.ts'healthUsingGet().then((response) => {console.log(response)
})</script>