说实话，Zuo前端开发的兄弟们，谁没经历过这种“至暗时刻”？后端同事兴冲冲地跑过来说：“接口geng新了Swagger文档Yi经同步，你那边对一下。”你打开浏览器，kan着那密密麻麻的字段，心里一阵发慌。时间一长，文档和代码对不上，前端抱怨接口不对，测试发现数据不对，Zui后在复盘会上，你莫名其妙成了团队里的“背锅侠”。这锅，背得冤不冤？真冤。

问题的核心在于：消除前端接口文件里手写类型的重复劳动。这不仅仅是为了偷懒，geng是为了生存。试想一下一个接口文件里躺着二三十个接口，参数全是`any`，你要是一个个去对照Swagger文档手写类型定义，这活儿干起来又枯燥又容易出错。哪怕你极其细心，只要后端稍微改个字段名，或者把必填项改成了可选，你这边要是没同步，线上就得炸。

痛点直击：为什么我们需要自动化？

我们来kankan日常开发中Zui常见的一幕。后端给你一个新接口，你打开接口文件，习惯性地写下：

export async function getModelListApi {
  return requestClient.post;
}

然后你打开 Swagger 文档，找到这个接口，kan着一堆字段，开始手动敲：

export interface GetModelListParams {
  code?: string;
  algoName?: string;
  status?: number;
  sceneId?: number;
  // ... 还有十几个字段
}

一个接口还好，要是几十个呢？要是字段名还特别长呢？这时候你肯定会想：这种机械性的、毫无营养的重复劳动，Neng不Neng交给机器去干？幸运的是AI 结合 Swagger 接口生成测试用例的创新方法为我们带来了突破性的解决方案，Swagger 是一个强大的 API 文档生成工具，它Neng够自动生成清晰、易读的 API 文档。在 AI 结合 Swagger 接口生成测试用例的过程中，高质量的 Swagger 文档起着至关重要的作用。

但这还不够，我们不仅要测试用例，我们要的是代码。我们要的是Neng直接跑在前端项目里的 TypeScript 类型定义。

破局之道：利用 AI 构建自动化工具

与其每天抱怨，不如动手解决。我Zui近就在琢磨，Neng不Neng利用现在的 AI Neng力，搞一个工具，专门解决这个痛点。这个工具的核心思路其实hen简单：用 AST 解析找到需要处理的函数，从 Swagger 拉取 Schema，转换成 TypeScript 类型，精准写入文件。整个过程自动化，不需要人工介入。

在动手写代码之前，我梳理了几个核心问题。这hen关键，hen多人用 AI 写代码，上来就说“帮我写一个 xxx 工具”，然后得到一堆不Neng用的代码。我的Zuo法是先描述问题，不急着让它写代码。

我对 AI 说：“我有一个前端项目，接口文件里有hen多函数参数是 any 类型，我想从 Swagger 文档自动生成 TypeScript 类型定义插入到文件里。你帮我梳理一下这个工具需要Zuo哪些事情。”

这一步的关键是不要让 AI 直接写代码，先把设计定下来。AI 给出了 6 个模块的划分，每个模块的输入输出接口，以及完整的数据流。这份设计文档后来成了整个开发过程的“合同”——每个模块按接口开发，互不干扰。

1. 模块化设计：让 AI 也Neng“按图施工”

基于这些需求，AI 帮我设计了这个工具的架构，包括模块划分、每个模块的接口定义、数据流向。整个工具拆成 6 个独立模块，每个模块只Zuo一件事：

bin/index.ts          # 入口，解析命令行参数
src/parser.ts         # 解析接口文件，提取函数信息
src/fetcher.ts        # 请求 Swagger 文档
src/converter.ts      # Schema → TypeScript 类型字符串
src/writer.ts         # 将类型写入文件
src/config.ts         # 读取配置文件
src/ref-resolver.ts   # 递归解析 $ref 引用
src/mcp-server.ts     # MCP Server 实现

这样每个模块Ke以独立测试，出问题也好定位。CLI 和 MCP Server 共用同一套核心引擎，入口层只负责参数解析和结果格式化，核心逻辑不重复。

2. 核心实现：从 AST 到 Swagger 的精准映射

设计文档确认后让 AI 把开发任务拆成具体的实现步骤。拆出来大概 10 个任务，从“初始化项目结构”到“实现 CLI 入口”，顺序是按依赖关系排的——先实现底层模块，再实现上层，Zui后串联成完整流程。

我们来kankan具体的技术细节。

识别哪些函数需要处理

不是所有函数dou要处理，只处理参数类型是 `any` 或者没有类型的函数。Yi经有明确类型定义的函数直接跳过不重复生成。判断是否需要处理的逻辑hen简单：参数类型是 `any` 或者根本没有类型注解，就加入待处理列表。

用 `ts.createSourceFile` Zuo AST 解析，识别这类调用模式：

requestClient.get;
requestClient.post;
requestClient.put;
requestClient.delete;

从 AST 里提取出：函数名、HTTP 方法、路径、当前参数类型。

怎么找到对应的 Swagger 接口

接口文件里的函数调用了 `requestClient.post`，需要从这里提取出 HTTP 方法和路径，然后去 Swagger 文档里找到对应的定义。

这里有个坑：实际项目里经常遇到，代码里的路径是 `/algo/model/list`，但 Swagger 文档里只有 `/model/list`。需要支持配置前缀来处理这种情况。

还有一个细节，Swagger UI 的地址和实际的 JSON 数据接口是两个不同的地址。工具会自动转换：

https://your-api/doc.html    → 先尝试 https://your-api/v3/api-docs
    → 失败则尝试 https://your-api/v2/api-docs

所以你直接把浏览器里的 Swagger 地址粘进来就行，不用手动改。

类型转换的艺术

基础类型映射hen简单，复杂的是这几种情况：`oneOf` / `anyOf` / `allOf`。

oneOf / anyOf → 联合类型 A | B
allOf         → 交叉类型 A & B

Swagger Schema 里有 `required` 数组，不在里面的字段生成时加 `?`：

export interface GetModelListParams {
  code?: string; // 不在 required 里加 ?
  status: number; // 在 required 里不加 ?
}

Swagger 里每个字段dou有 `description`，直接转成 JSDoc：

export interface GetModelListParams {
  /** 算法编码 */
  code?: string;
  /** 状态：-禁用 -启用 */
  status?: number;
}

Swagger 里经常有这种结构：

{
  "schema": { "$ref": "#/components/schemas/ModelVO" }
}

`ModelVO` 里可Neng又引用了其他类型，需要递归解析，同时用 `Set` 去重，避免同一个类型被生成多次。

3. 写入文件：精准插入，不破坏原有代码

这是Zui危险的一步。写入逻辑分两步：生成的类型要插入到函数上方，同时把函数参数里的 `any` 替换掉，但其他代码一行dou不Neng动。

用行号定位插入位置，其他行的内容原封不动。写入前先检查文件里是否Yi有同名类型，有的话直接跳过。

设计文档里还有一个我觉得hen有价值的部分：正确性属性。AI 把每个模块应该满足的行为约束dou列出来了比如“写入幂等性：同一个文件跑两次结果不变”、“dry-run 不修改文件”。这些属性后来直接变成了属性测试的用例。

避坑指南：如何正确地“调教”AI

整个工具从开始到发布 npm，大概花了一个下午。Ru果纯手写，光设计文档和测试就得好几天。但是过程中并不是一帆风顺的。用 AI 开发工具，Zui重要的不是“怎么让 AI 写代码”，而是怎么把问题描述清楚。

这里有一条黄金法则：遇到问题描述现象，不要猜原因。

比如我实际跑的时候发现：`defaultFiles` 配置了多个文件，但实际只处理了第一个。这时候，不要对 AI 说“我觉得是循环逻辑有问题”，这种猜测往往会误导 AI。你应该直接说：“defaultFiles 只处理了第一个文件”。

AI 直接定位到 `bin/index.ts` 里的那行代码，改成了遍历逻辑。你kan，描述现象比猜测原因高效得多。

还有一次单个接口处理失败，影响了其他接口继续处理。我告诉 AI：“单个接口处理失败，不影响其他接口继续处理。” AI 随即调整了错误处理策略，所有错误dou以结构化对象返回，不抛出未处理的异常：

type ErrorType =
  | "SWAGGER_FETCH_ERROR" // Swagger 文档无法访问
  | "ENDPOINT_NOT_FOUND" // 找不到对应接口
  | "PARSE_ERROR" // 文件解析失败
  | "WRITE_ERROR" // 文件写入失败
  | "CONFIG_NOT_FOUND"; // 没有配置文件也没有传参数

实战演练：如何使用这个工具

工具本地测试没问题后让 AI 帮我处理发布相关的事情。现在这个工具Yi经支持两种使用方式：CLI 命令行 和 MCP Server。

方式一：CLI 命令行

先全局安装：

npm install -g swagger-ts-mcp

在项目根目录创建配置文件 `swagger-ts-gen.config.json`：

{
  "swaggerUrl": "https://your-api/doc.html",
  "defaultFiles": ,
  "endpointPrefix": "/algo"
}

然后直接运行：

swagger-ts-mcp --file src/api/user.ts --swagger https://your-api/doc.html

建议先用 `--dry-run` 预览，确认没问题再正式执行：

swagger-ts-mcp --file src/api/user.ts --swagger https://your-api/doc.html --dry-run

方式二：MCP Server：让 AI IDE 直接调用

MCP是一个让 AI IDE 调用外部工具的协议。工具以 stdio 方式启动，暴露一个 `generate_types` 工具：

{
  name: "generate_types",
  inputSchema: {
    filePath: string,      // 必填：目标文件路径
    swaggerUrl?: string,   // 可选：Swagger 地址
    functionNames?: string, // 可选：只处理这些函数
    dryRun?: boolean       // 可选：预览模式
  }
}

在 `.cursor/mcp.json` 里添加：

{
  "mcpServers": {
    "swagger-ts-mcp": {
      "command": "npx",
      "args": 
    }
  }
}

`Cmd+Shift+P` → Reload MCP Servers，然后在 Composer 里说：“使用 swagger-ts-mcp 工具，帮我给 src/api/user.ts 生成类型”。AI 会自动调用工具完成处理。

配置好之后在 Kiro 或 Cursor 里直接说“帮我给这个文件生成类型”，AI 会自动调用工具完成处理。MCP Server 模式让它Ke以直接集成到 AI IDE 的工作流里配合 Kiro 或 Cursor 使用体验geng顺滑。

把时间留给geng有价值的事

这就是我Zuo这个工具的原因。所有内容dou来自代码注释或配置，改接口就自动geng新文档，永不脱节。原生 OpenAPI 支持：只要写好函数签名和类型注解，文档就自动生成，无需额外插件或配置。

试着使用 Claude Code 进行一次优化，询问这个项目还有哪些需要优化的地方，其中“支持本地 Swagger/OpenAPI JSON 文件输入”是我自己另外指导加的一个规则，其他的dou是 AI 生成的。然后逐步进入开发，先完成 p0 再完成 p1，包体积大小Yi经优化、本地离线 json 也Yi支持。npm 下载量Yi经有了六百多个~

有问题或者建议欢迎提 issue。项目地址：github.com/lhbDesign/s…

Zui后几个实际有用的Zuo法：

按模块推进，每步验证。不要让 AI 一次性把所有代码dou写完，按模块来每个模块实现完跑测试确认，再继续下一个。

设计先于实现。让 AI 出设计文档，确认接口定义，再开始写代码。跳过这步直接写代码，后面改起来hen痛苦。

让 AI 生成测试。属性测试特别适合让 AI 来写，它Neng覆盖到你手动写用例时想不到的边界情况。

希望这个工具Neng帮你从繁琐的接口对齐工作中解脱出来把精力花在geng复杂的业务逻辑上。毕竟我们的目标是星辰大海，而不是复制粘贴。

---