使用AI完成Swagger接口类型在前端自动生成的工具

厌倦了手写 TypeScript 类型我做了一个工具帮你从 Swagger 自动生成背景一个让人抓狂的日常做前端的同学应该都经历过这种场景后端给你一个新接口你打开接口文件写下exportasyncfunctiongetModelListApi(params?:any){returnrequestClient.post(/algo/model/list,params);}然后你打开 Swagger 文档找到这个接口看着一堆字段开始手动敲exportinterfaceGetModelListParams{code?:string;algoName?:string;status?:number;sceneId?:number;// ... 还有十几个字段}一个接口还好一个文件里有二三十个接口全是any这活儿干起来又枯燥又容易出错。这就是我做这个工具的原因。工具介绍swagger-ts-mcp 是一个从 Swagger/OpenAPI 文档自动为前端接口文件生成 TypeScript 类型定义的工具。核心能力解析你的接口文件找出所有参数类型为any或未定义的函数自动从 Swagger 文档拉取对应接口的 Schema生成规范的 TypeScript interface插入到函数上方把函数参数里的any替换成具体类型名支持两种使用方式CLI 命令行和MCP Server给 Kiro、Cursor 等 AI IDE 用。效果展示处理前// 取消发布exportasyncfunctioncancelPublishApi(params?:any){returnrequestClient.get(/model/publish/cancel,{params});}处理后/** 取消发布请求参数 */exportinterfaceCancelPublishParams{/** 模型ID */modelId?:number;}// 取消发布exportasyncfunctioncancelPublishApi(params?:CancelPublishParams){returnrequestClient.get(/model/publish/cancel,{params});}一个文件里几十个接口一条命令全部搞定。需求分析这个工具到底要解决什么在动手写代码之前我梳理了几个核心问题1. 识别哪些函数需要处理不是所有函数都要处理只处理参数类型是any或者没有类型的函数。已经有明确类型定义的函数直接跳过不重复生成。2. 怎么找到对应的 Swagger 接口接口文件里的函数调用了requestClient.post(/algo/model/list, params)需要从这里提取出 HTTP 方法post和路径/algo/model/list然后去 Swagger 文档里找到对应的定义。3. 路径前缀问题实际项目里经常遇到代码里的路径是/algo/model/list但 Swagger 文档里只有/model/list前缀/algo是网关加的。需要支持配置前缀来处理这种情况。4. 写入不能破坏原有代码生成的类型要插入到函数上方同时把函数参数里的any替换掉但其他代码一行都不能动。5. 幂等性同一个文件跑两次不能生成重复的类型定义。如果类型已经存在直接跳过。设计理念模块化职责单一整个工具拆成 6 个独立模块每个模块只做一件事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 实现这样每个模块可以独立测试出问题也好定位。错误不抛异常结构化返回所有错误都以结构化对象返回不抛出未处理的异常typeErrorType|SWAGGER_FETCH_ERROR// Swagger 文档无法访问|ENDPOINT_NOT_FOUND// 找不到对应接口|PARSE_ERROR// 文件解析失败|WRITE_ERROR// 文件写入失败|CONFIG_NOT_FOUND;// 没有配置文件也没有传参数单个接口处理失败比如 Swagger 里找不到这个路径不影响其他接口继续处理。两种调用方式同一套核心逻辑CLI 和 MCP Server 共用同一套核心引擎入口层只负责参数解析和结果格式化核心逻辑不重复。实现细节1. 解析接口文件用 TypeScript Compiler API用ts.createSourceFile做 AST 解析识别这类调用模式requestClient.get(path,{params});requestClient.post(path,data);requestClient.put(path,data);requestClient.delete(path,{params});从 AST 里提取出函数名、HTTP 方法、路径、当前参数类型。判断是否需要处理的逻辑很简单参数类型是any或者根本没有类型注解就加入待处理列表。2. 获取 Swagger 文档自动处理 URL 转换Swagger UI 的地址doc.html和实际的 JSON 数据接口/v3/api-docs是两个不同的地址。工具会自动转换https://your-api/doc.html → 先尝试 https://your-api/v3/api-docs → 失败则尝试 https://your-api/v2/api-docs所以你直接把浏览器里的 Swagger 地址粘进来就行不用手动改。3. Schema 转换处理各种复杂情况基础类型映射很简单复杂的是这几种情况$ref递归引用Swagger 里经常有这种结构{schema:{$ref:#/components/schemas/ModelVO}}ModelVO里可能又引用了其他类型需要递归解析同时用Set去重避免同一个类型被生成多次。oneOf/anyOf/allOfoneOf / anyOf → 联合类型 A | B allOf → 交叉类型 A B可选字段Swagger Schema 里有required数组不在里面的字段生成时加?exportinterfaceGetModelListParams{code?:string;// 不在 required 里加 ?status:number;// 在 required 里不加 ?}JSDoc 注释Swagger 里每个字段都有description直接转成 JSDocexportinterfaceGetModelListParams{/** 算法编码 */code?:string;/** 状态0-禁用 1-启用 */status?:number;}4. 写入文件精准插入不破坏原有代码写入逻辑分两步在函数定义行的上方插入类型定义把函数参数里的any替换成生成的类型名用行号定位插入位置其他行的内容原封不动。写入前先检查文件里是否已有同名类型有的话直接跳过幂等性保证。5. 命名规范函数名到类型名的转换规则getUserListApi → 去掉 Api 后缀 → getUserList → 首字母大写 → GetUserList → 加后缀 → GetUserListParams / GetUserListResult6. MCP Server让 AI IDE 直接调用MCPModel Context Protocol是一个让 AI IDE 调用外部工具的协议。工具以 stdio 方式启动暴露一个generate_types工具{name:generate_types,inputSchema:{filePath:string,// 必填目标文件路径swaggerUrl?:string,// 可选Swagger 地址优先于配置文件functionNames?:string[],// 可选只处理这些函数dryRun?:boolean// 可选预览模式}}配置好之后在 Kiro 或 Cursor 里直接说帮我给这个文件生成类型AI 会自动调用工具完成处理。使用方式安装npminstall-gswagger-ts-mcp方式一CLI在项目根目录创建配置文件swagger-ts-gen.config.json{swaggerUrl:https://your-api/doc.html,defaultFiles:[src/api/user.ts,src/api/order.ts],endpointPrefix:/algo}然后直接运行swagger-ts-mcp也可以不用配置文件直接传参数swagger-ts-mcp--filesrc/api/user.ts--swaggerhttps://your-api/doc.html先用--dry-run预览确认没问题再正式执行swagger-ts-mcp--filesrc/api/user.ts--swaggerhttps://your-api/doc.html --dry-runnpx 的方式使用方式二MCP ServerKiro在.kiro/settings/mcp.json里添加{mcpServers:{swagger-ts-mcp:{command:npx,args:[swagger-ts-mcp,--mcp],autoApprove:[generate_types]}}}然后在聊天框里说帮我给 src/api/user.ts 生成 TypeScript 类型方式二MCP ServerCursor在.cursor/mcp.json里添加{mcpServers:{swagger-ts-mcp:{command:npx,args:[swagger-ts-mcp,--mcp]}}}CmdShiftP→ Reload MCP Servers然后在 Composer 里说使用 swagger-ts-mcp 工具帮我给 src/api/user.ts 生成类型支持的 API 文档工具工具使用方式Swagger / SpringDoc直接传doc.html地址自动转换Knife4j同 Swagger完全兼容YApi使用导出 URL/api/plugin/export?typeswaggerpidxxxtokenxxxApifox项目设置 → 导出 OpenAPI 3.0 URL配置项说明配置项说明swaggerUrlSwagger 文档地址defaultFiles默认处理的文件列表支持多个endpointPrefix路径前缀。代码里是/algo/user/listSwagger 里是/user/list设为/algoclientNameHTTP 客户端名称默认requestClient可改为axios等outputStyle生成interface还是type默认interface用 AI 开发这个工具的完整过程这个工具从需求到上线全程在 KiroAI IDE里完成没有手写一行架构代码。说一下我是怎么引导 AI 一步步做出来的。第一步描述痛点让 AI 帮你想清楚需求很多人用 AI 写代码上来就说帮我写一个 xxx 工具然后得到一堆不能用的代码。我的做法是先描述问题不急着让它写代码我有一个前端项目接口文件里有很多函数参数是 any 类型我想从 Swagger 文档自动生成 TypeScript 类型定义插入到文件里。你帮我梳理一下这个工具需要做哪些事情。AI 会帮你把需求拆解成具体的验收标准这个过程本身就是在帮你想清楚边界条件——比如已有类型的函数要不要处理、“路径前缀怎么处理”、“写入失败怎么办”这些细节如果一开始没想清楚后面写代码会反复返工。Kiro 有专门的 Spec 功能可以把需求、设计、任务拆解都沉淀成文档后续开发全程参照这些文档不会跑偏。第二步需求确认后让 AI 出设计文档需求文档确认后让 AI 基于需求出设计方案基于这些需求帮我设计这个工具的架构包括模块划分、每个模块的接口定义、数据流向。这一步的关键是不要让 AI 直接写代码先把设计定下来。AI 给出了 6 个模块的划分Parser、Fetcher、Converter、Writer、Config、RefResolver每个模块的输入输出接口以及完整的数据流。这份设计文档后来成了整个开发过程的合同——每个模块按接口开发互不干扰。设计文档里还有一个我觉得很有价值的部分正确性属性。AI 把每个模块应该满足的行为约束都列出来了比如写入幂等性同一个文件跑两次结果不变、“dry-run 不修改文件”。这些属性后来直接变成了属性测试的用例。第三步任务拆解按模块逐个实现设计文档确认后让 AI 把开发任务拆成具体的实现步骤基于设计文档帮我把实现拆成具体的任务列表每个任务对应一个模块标注依赖的需求条款。拆出来大概 13 个任务从初始化项目结构到实现 CLI 入口顺序是按依赖关系排的——先实现底层模块Config、Fetcher、Converter再实现上层Parser、Writer最后串联成完整流程MCP Server、CLI。每个任务里还有对应的测试任务单元测试和属性测试都在里面。然后就是按任务列表逐个让 AI 实现现在实现任务 3Swagger Fetcher。按照设计文档里的接口定义来实现 URL 转换逻辑和错误处理。每个模块实现完让 AI 跑一下对应的测试确认通过再继续下一个。第四步联调和边界情况处理各模块实现完之后串联起来跑真实场景这时候会发现一些设计时没考虑到的问题。比如我实际跑的时候发现defaultFiles配置了多个文件但只处理了第一个——因为 CLI 入口里只取了config.defaultFiles?.[0]需要改成遍历所有文件Swagger 地址需要登录认证的情况没有友好提示这些问题直接描述给 AI让它定位并修复defaultFiles 配置了多个文件但实际只处理了第一个帮我找一下问题在哪里修复。AI 直接定位到bin/index.ts里的那行代码改成了遍历逻辑。第五步发布和文档完善工具本地测试没问题后让 AI 帮我处理发布相关的事情完善package.json补充description、keywords、files、engines等字段生成.gitignore和.npmignore把 README 从中文扩展成中英双语后来改成两个独立文件我的体会用 AI 开发工具最重要的不是怎么让 AI 写代码而是怎么把问题描述清楚。几个实际有用的做法先描述问题不要直接要代码。让 AI 帮你梳理需求这个过程会暴露你自己没想清楚的地方。设计先于实现。让 AI 出设计文档确认接口定义再开始写代码。跳过这步直接写代码后面改起来很痛苦。按模块推进每步验证。不要让 AI 一次性把所有代码都写完按模块来每个模块实现完跑测试确认再继续下一个。遇到问题描述现象不要猜原因。defaultFiles 只处理了第一个文件比我觉得是循环逻辑有问题更容易让 AI 定位到正确位置。让 AI 生成测试。属性测试Property-based testing特别适合让 AI 来写它能覆盖到你手动写用例时想不到的边界情况。整个工具从开始到发布 npm大概花了一个下午。如果纯手写光设计文档和测试就得好几天。更新试着使用 cluade code 进行一次优化询问这个项目还有哪些需要优化的地方其中 ###6. 支持本地 Swagger/OpenAPI JSON 文件输入离线/内网场景 是我自己另外指导加的一个规则其他的都是 ai 生成的。 然后逐步进入开发先完成 p0 再完成 p1 包体积大小已经优化、本地离线json也已支持。npm下载量已经有了四百多个~cluade code自动生成更新日志总结这个工具解决的问题很具体消除前端接口文件里手写类型的重复劳动。核心思路是用 AST 解析找到需要处理的函数从 Swagger 拉取 Schema转换成 TypeScript 类型精准写入文件。整个过程自动化不需要人工介入。MCP Server 模式让它可以直接集成到 AI IDE 的工作流里配合 Kiro 或 Cursor 使用体验更顺滑。项目地址https://github.com/lhbDesign/swagger-ts-gennpmhttps://www.npmjs.com/package/swagger-ts-mcp有问题或者建议欢迎提 issue。