Yapi Toolkit

💡 高效的类型生成解决方案 — 你可能会爱上它，闪电般同步 YAPI 接口文档，智能生成 TypeScript 类型定义。

一键同步 YAPI 文档，自动生成 TypeScript 类型定义，零维护成本。仅需三步配置，省去繁琐的手动编写。

🎬 功能演示

✨ 特性

• 🚀 全量生成 - 一键生成所有接口的 TypeScript 类型定义
• 📊 实时反馈 - 状态栏实时显示生成进度和耗时统计
• ⚡ 极速生成 - 秒级响应，轻松处理大规模接口生成
• 🔄 自动同步 - 接口变更自动更新类型定义，无需人工维护
• 💰 零维护成本 - 无过期代码风险，永远与 YAPI 保持同步

📋 快速开始

第一步: 安装本插件并配置 YAPI 信息

1. 在 Cursor 界面中，使用以下快捷键打开命令面板：

   • Ctrl + Shift + P (Windows/Linux)
   • Cmd + Shift + P (macOS)

2. 输入 配置 YAPI，选择【配置 YAPI】，按 Enter 键进入配置界面。

3. 依次输入【服务器地址】和【项目 Token】，点击【加密 Token】按钮，插件会自动生成加密后的 Token。

4. 可选择【测试配置连接】验证配置是否正确。

5. 选择【配置保存位置】：

   • .vscode/settings.json - 团队共享配置（会提交到版本控制，团队成员共用）
   • .vscode/yapi-toolkit.json - 个人私有配置（建议加入 .gitignore，仅本地使用）

6. 点击【保存配置】，配置信息将保存到选择的文件中。

配置界面预览：

⚠️ 重要提示：配置保存后会提示是否重启 Cursor，建议重启以确保配置立即生效。

第二步: 生成 TypeScript 类型

点击 VSCode 状态栏右下角的 EasyYapi 按钮，插件将根据配置信息从 YAPI 服务器拉取接口文档，并自动生成对应的 TypeScript 类型定义。

第三步: 使用生成的类型

生成后的文件结构：

src/service/
├── model/              # 各模块的参数类型定义
│   ├── login.ts        # 登录模块示例
│   └── addresses.ts    # 地址模块示例
└── typings.d.ts        # 类型声明汇总文件

生成规则说明

插件根据 YAPI 接口定义自动生成 TypeScript 类型，遵循以下规则：

示例解析：

对于接口 POST /login/getLoginUser：

• 接口名：GetLoginUser（对应路由最后一段转为 PascalCase）
• 入参类型：GetLoginUserInput（用于传递请求参数）
• 回参类型：GetLoginUser（用于定义响应数据结构）

// 入参类型（请求参数）
export type GetLoginUserInput = {
  /** 用户Id */
  useId: string;
};


// 回参类型（响应数据）
export type GetLoginUser = {
  /** 用户名 */
  useName: string;
  /** 年龄 */
  age: string;
};

📝 实际应用示例

以下是如何在项目中使用生成的类型定义的完整示例：

import { YAPI_login } from "./service/typings";

/** API响应的通用结构 */
interface ApiResponse<T> {
  data: T;
  code?: number;
  message?: string;
}

/** 发送post请求通用方法，这里展示如何使用 typescript 类型来定义请求参数和返回值 */
const postApi = <T, R>(url: string, params: T): Promise<ApiResponse<R>> => {
  return fetch(url, {
    method: "POST",
    body: JSON.stringify(params),
  })
    .then((res) => res.json())
    .then((data) => {
      return data as ApiResponse<R>;
    });
};

const getLoginUserApi = (params: YAPI_login.GetLoginUserInput) => {
  return postApi<any, YAPI_login.GetLoginUser>("/login/getLoginUser", params);
};

/** 入参和响应返回值均具备完整的类型提示，配合 AI 工具甚至可以实现自动联调接口 */
getLoginUserApi({ useId: "10" }).then((res) => {
  const resData = res.data?.useName;
});

常见问题

Q1: 生成失败了怎么办？

检查清单：

• ✅ 确保 serverUrl 和 token 配置正确
• ✅ 确认网络连接正常，能访问 YAPI 服务器
• ✅ 检查配置文件位置：配置成功保存在 .vscode/settings.json 或 .vscode/yapi-toolkit.json，确保文件存在且格式正确

Q2: 生成的类型文件在哪里？

默认生成位置为 src/service/model 目录（如需修改请参考 Q3）。

每个 API 名称的前缀对应一个文件，例如 /login/getLoginUser 会生成 src/service/model/login.ts 文件。

Q3: 可以自定义生成路径吗？

可以通过配置界面中的【生成路径】字段自定义路径，或直接修改配置文件：

• .vscode/settings.json 中的 yapi-toolkit.basePath 属性
• .vscode/yapi-toolkit.json 中的 basePath 属性

Q5: 如何只生成返回数据中某个字段的类型？

如果 API 返回格式为 { code: 200, data: { list: [...] } }，而你只想生成 list 的类型，可以在配置界面中设置【响应数据路径】为 data.list。

配置示例：

• 返回格式：{ code: 200, data: { list: [...] } }
• 配置 responseDataPath 为 data.list
• 生成结果：只生成 list 的类型定义

配置方式：

• 在配置界面的【高级配置】卡片中设置【响应数据路径】

Q4: 为什么不生成 API 请求函数？

本插件专注于类型定义生成。API 请求函数需要根据实际项目需求进行编写，主要原因如下：

1. 接口生命周期管理 - 后端接口可能被删除、重构或迁移，自动生成的请求函数会成为"死代码"
2. 隐藏潜在风险 - 过时的请求函数仍存在于项目中，使用时可能导致运行时错误
3. 项目安全 - 需要由开发者显式编写和维护请求函数，确保代码质量和项目稳定性

对比：为什么类型定义不同？

• ✅ 类型定义自动同步 - 每次重新生成时，所有类型定义都会自动覆盖更新
• ✅ 零维护成本 - 接口删除时，相应的类型定义也会消失，不会出现过时代码
• ✅ 永远与接口同步 - 无需担心类型与实际接口不匹配的问题
• ✅ 开发效率高 - 专注编写业务逻辑，不用手动维护类型定义

故障排除

📄 许可证

MIT License - 详见 LICENSE 文件

如有任何问题或建议，请通过以下方式反馈：

• 发送邮件至 imjinxihexi@163.com