Spring Boot整合knife4j实战

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

文章目录

前言
[一、Spring Boot整合knife4j](#一、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：

xml 复制代码

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

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

yml 复制代码

# 接口文档相关配置（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：定义方法参数的含义

java 复制代码

@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：字段的含义

java 复制代码

@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管理工具，则使用如下命令导入：

javascript 复制代码

npm i --save-dev @umijs/openapi

导入成功后，在package.json中可以看到对应的依赖：

在项目的根目录下创建openapi.config.js文件，@umijs/openapi 只需要后端提供符合 OpenAPI 规范的接口文档（无论是通过 Swagger、knife4j 还是其他工具生成的），就能完成代码生成工作。而knife4j是后端接口文档的增强工具，它本质上还是基于 OpenAPI 规范输出接口文档，因此可以作为 @umijs/openapi 的 "数据源" 之一，但并非唯一选择。

javascript 复制代码

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中导入，启动项目查看效果：

javascript 复制代码

<script setup lang="ts">
import { healthUsingGet } from '@/api/mainController.ts'

healthUsingGet().then((response) => {
  console.log(response)
})

</script>