还在手写接口请求？用 Knife4j + OpenAPI 自动生成前端 API，开发效率提升 10 倍

在 AI 辅助编程日益流行的今天，为什么我们还要关注自动生成代码？因为可控性和准确性依然是工程化开发的基石。
本文带你体验一套高效、可靠的前后端协作方案：后端用 Knife4j 生成美观的接口文档，前端用 OpenAPI 工具一键生成 TypeScript 请求代码。从此告别手动维护 API 的烦恼，让代码自动同步，准确又高效。

---

一、手动写 API 的痛，你经历过几个？

在前后端分离的开发模式中，前端需要根据后端的接口定义编写大量的请求函数和数据模型。这个过程通常是这样：

• 后端写好接口，提供 Swagger 文档。
• 前端打开文档，照着接口路径、参数、返回值手写 axios 请求，并定义 TypeScript 类型。
• 如果接口有 50 个，就要手写 50 次类似的代码，枯燥且重复。
• 一旦后端接口变更（比如路径从 /user/list 改成 /user/page，或者新增字段），前端需要手动查找所有相关代码并修改，极易遗漏或出错。

有人会说：“现在 AI 这么强，为什么不直接让 AI 写？”
AI 确实能生成一部分代码，但存在几个问题：

• AI 可能“幻觉”，生成与实际文档不符的代码。
• 接口更新后，AI 不会自动同步，仍需人工介入。
• 团队协作中，依赖 AI 生成难以保证一致性。

自动生成代码则完美解决了这些问题：

• ✅ 完全自动：一条命令生成所有 API 代码。
• ✅ 100% 对齐文档：基于实时 OpenAPI JSON 生成，保证准确性。
• ✅ 类型安全：自动生成 TypeScript 类型，IDE 智能提示拉满。
• ✅ 可控性强：生成逻辑由配置文件决定，无“黑盒”。
• ✅ 接口变更一键更新：重新运行命令即可同步。

---

二、先理解几个概念

2.1 Swagger 是什么？

Swagger 是一套用于描述、生成、消费和可视化 RESTful Web 服务的规范与工具集。它定义了一套 OpenAPI 规范（原 Swagger 规范），开发者通过注解或配置文件定义 API 信息，然后由工具自动生成可交互的 API 文档。

简单来说，后端只需要在代码里加一些注解，就能得到一个实时更新的 API 文档页面，前端可以直接在上面查看接口详情，甚至发起测试请求。

在 Spring Boot 中，集成 Swagger 的常用方式是使用 springdoc-openapi（Spring Boot 3）或 springfox（旧版）。启动项目后，访问 http://localhost:8080/swagger-ui.html 或 http://localhost:8080/v3/api-docs 就能看到文档和 JSON 数据。

2.2 Knife4j：Swagger 的增强工具

Knife4j 是 Swagger 的增强工具，它在保留 Swagger 原有功能的基础上，提供了更美观的 UI 界面、文档分组、离线文档等功能。简单来说，它让后端接口文档变得更好看、更好用。

你只需要在后端 Spring Boot 项目中引入 Knife4j 依赖，稍作配置，就能得到一个类似 http://localhost:8080/doc.html 的接口文档页面。同时，它依然会提供标准的 OpenAPI JSON 地址（如 http://localhost:8080/v3/api-docs），供前端工具消费。

2.3 OpenAPI 是什么？

OpenAPI 是接口文档的标准格式，本质是一个 JSON 文件，描述了所有接口的路径、参数、返回值、数据类型等信息。
例如：http://localhost:8123/v3/api-docs 返回的就是这样一个 JSON。前端自动生成工具就是基于这个 JSON 来生成请求代码和 TypeScript 类型。

---

三、整体流程

整个自动化流程非常简单清晰：

后端 SpringBoot
       ↓
Knife4j 生成 OpenAPI JSON 文档
       ↓
前端读取 OpenAPI JSON 地址
       ↓
openapi2ts 工具自动生成请求代码 + 类型定义
       ↓
前端直接使用生成的 API

最终效果：接口文档 → 自动生成前端 API，接口变更只需重新生成。

---

四、后端准备：集成 Knife4j

首先，确保你的 Spring Boot 项目已经集成了 Knife4j。

4.1 添加依赖（Spring Boot 3 示例）

在 pom.xml 中添加：

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

如果你的 Spring Boot 版本低于 3，请使用对应的依赖（可参考 Knife4j 官方文档）。

4.2 启动项目，查看文档

启动后端服务，访问：http://localhost:8123/doc.html（端口根据你的项目配置调整），即可看到漂亮的 Knife4j 接口文档页面。

4.3 获取 OpenAPI JSON 地址

最关键的一步：找到 OpenAPI JSON 的访问地址，通常是 http://localhost:8123/v3/api-docs。
这个地址将被前端用于生成代码。注意：生成代码前必须确保后端服务已启动，且该地址可访问。

---

五、前端自动生成 API

现在进入前端项目，开始配置自动生成工具。我们使用 @umijs/openapi，它是一款成熟、好用的 OpenAPI 生成器。

5.1 安装依赖

在前端项目根目录下执行：

npm i --save-dev @umijs/openapi tslib

• @umijs/openapi：核心生成工具。
• tslib：TypeScript 运行时辅助库，某些生成代码会用到。

5.2 创建配置文件

在项目根目录新建 openapi2ts.config.ts，内容如下：

// openapi2ts.config.ts
export default {
  // 项目中封装的请求模块导入路径（根据你的实际路径调整）
  requestLibPath: "import request from '@/request'",
  // 后端提供的 OpenAPI JSON 地址（确保后端已启动）
  schemaPath: 'http://localhost:8123/v3/api-docs',
  // 生成代码的输出目录
  serversPath: './src',
}

参数说明：

• requestLibPath
  告诉工具你的请求函数从哪里导入。你需要提前在项目中封装好一个 request 模块（例如基于 axios），并导出。这里填写导入语句，工具会把它插入到每个生成的请求文件顶部。
  例如，你的 request.ts 位于 src/request.ts，则写 "import request from '@/request'"（假设配置了 @ 路径别名）。

• schemaPath
  后端 OpenAPI JSON 的完整 URL，就是上一步获取的地址。

• serversPath
  生成代码的存放目录。通常设为 './src'，工具会在 src 下创建 services 文件夹，并按接口标签（tag）分类存放生成的文件。

5.3 封装 request 模块（示例）

如果你还没有封装好的 request，可以参考以下基于 axios 的示例（src/request.ts）：

import axios from 'axios'
import { message } from 'ant-design-vue'

const myAxios = axios.create({
  baseURL: '/api',        // 根据你的实际接口前缀调整
  timeout: 60000,
  withCredentials: true,
})

// 请求拦截器
myAxios.interceptors.request.use(
  config => config,
  error => Promise.reject(error)
)

// 响应拦截器
myAxios.interceptors.response.use(
  response => response.data,   // 直接返回 data，具体根据后端返回结构调整
  error => {
    message.error('请求失败')
    return Promise.reject(error)
  }
)

export default myAxios

注意： 如果你的后端返回结构是 { code, data, message } 这种形式，你可能需要在拦截器中统一处理，或者让生成工具配合处理。这里为了简化，假设直接返回 response.data。

5.4 添加 npm 命令

在 package.json 的 scripts 中添加一条命令：

"scripts": {
  "openapi": "openapi2ts"
}

这样我们就可以通过 npm run openapi 来执行代码生成。

5.5 执行生成

确保后端服务已启动，然后在终端运行：

npm run openapi

如果一切顺利，你会看到类似如下的输出：

Generate API successfully

此时打开 src/services 目录，你会看到自动生成的代码结构：

src/services/
├── userController.ts      # 按控制器/标签生成的请求函数
├── orderController.ts
├── typings.d.ts           # 全局类型定义
└── ...                    # 更多文件

---

六、生成效果预览

我们来看一下自动生成的代码长什么样。

假设后端有一个登录接口，定义如下（Swagger 注解）：

• 路径：/api/user/login
• 方法：POST
• 请求体：LoginRequest（包含 username, password）
• 返回值：UserVO

那么生成的 userController.ts 中会包含：

// src/services/userController.ts
import request from '@/request';

export async function login(body: API.LoginRequest) {
  return request<API.UserVO>('/api/user/login', {
    method: 'POST',
    data: body,
  });
}

同时，typings.d.ts 中会自动生成对应的 TypeScript 类型：

// src/services/typings.d.ts
declare namespace API {
  type LoginRequest = {
    username?: string;
    password?: string;
  };

  type UserVO = {
    id?: number;
    username?: string;
    avatar?: string;
    // ... 其他字段
  };
}

所有类型都自动生成，无需手动定义！

---

七、在项目中使用生成的 API

使用起来非常简单，直接导入即可：

import { login } from '@/services/userController';

const handleLogin = async () => {
  try {
    const res = await login({ username: 'admin', password: '123456' });
    console.log('登录成功', res);
  } catch (error) {
    console.error('登录失败', error);
  }
};

IDE 会提供完整的类型提示，参数和返回值都有智能补全，极大提升开发体验和代码健壮性。

---

八、接口变更了怎么办？

这是自动生成的最大优势。

假设后端修改了登录接口：

• 新增了一个字段 captcha
• 返回值中增加了 token 字段

你只需要重新运行生成命令：

npm run openapi

所有相关的请求函数和类型定义都会自动更新，无需手动查找和修改。你的业务代码中，如果使用了新字段，TypeScript 会立即提示类型错误，让你能快速适配。

---

九、最佳实践与注意事项

9.1 推荐的目录结构

src/
├── request.ts               # 封装的请求实例
├── api/                # 自动生成的 API（不手动修改）
├── pages/                   # 页面组件
├── utils/                   # 工具函数
└── ...

注意：api 目录下的文件是自动生成的，不要手动修改，否则下次生成时会覆盖。如果需要自定义某些请求（如添加特殊 headers），可以在调用处封装一层，或者通过 request 拦截器统一处理。

9.2 将生成命令集成到开发流程

• 可以添加到 package.json 的 postinstall 脚本，确保每次安装依赖后自动生成最新 API：

  "scripts": {
    "postinstall": "npm run openapi"
  }
  

• 也可以在项目启动脚本前执行生成，保证代码最新。

9.3 多环境支持

如果不同环境（开发、测试、生产）的接口地址不同，可以通过环境变量动态设置 schemaPath。例如，在配置文件中读取 process.env.API_DOCS_URL。

---

十、总结

通过 Knife4j + OpenAPI 自动生成请求代码，我们实现了：

• 后端接口文档与前端请求代码的强一致性。
• 前端开发者零手写请求函数，只需关注业务逻辑。
• 类型安全，IDE 智能提示，减少低级错误。
• 接口变更时，一键同步，极大提升协作效率。

在 AI 辅助编程越来越普及的今天，这种自动化工具依然有着不可替代的价值——它保证了代码的确定性和可控性。当你需要快速迭代、多人协作时，这套方案能让团队如虎添翼。

赶快在你的项目中试试吧！如果你有任何疑问或更好的实践，欢迎在评论区交流。