快速将swagger转ts的几种方法

nys013 2025/10/9 swaggerTSMCP

# 前言

前面几种是开始尝试的方法，省流可跳过尝试，直接看后两种方法

# 尝试

# orval (opens new window)

这个用的人多，以下是一些常用配置

swagger目标文件配置：可本地json/yaml文件，也可在线json文件地址

在线地址需用户名和密码的话，可以在url中拼接用户名和密码，就能访问了

如https://petstore3.swagger.io/api/v3/openapi.json 拼接为 https://username:password@petstore3.swagger.io/api/v3/openapi.json

可以通过配置filter过滤指定接口类，以免swagger文档过大输出慢，且输出许多不需要的接口
自定义请求函数实例的配置
可以将model和api分开文件存放

因为orval没有用户名密码的配置项，开始以为对于有密码的swagger在线文件就处理不了，只能下载到本地处理，比较麻烦，所以就选用api-helper了

# api-helper (opens new window)

用的人不算多，比较小众

因为是先用过一段时间api-helper，没什么问题，和orval类似的效果，配置项和优缺点差不多，就没有再改用其他主流的库了

感觉和orval的区别是：对于线上链接，可以配置auth的账户密码，不用自己拼接url了

常用配置如下：

// apih.config.js文件
import { defineConfig } from '@api-helper/cli';

export default defineConfig({
  // 是否只生成接口请求数据和返回数据的 TypeScript 类型。是，则请求文件和请求函数都不会生成。
  onlyTyping: false,
  // 代码生成后的输出路径
  outputPath: 'src/api/pet.ts',
  // 使用分类输出，启用该功能后，按照接口分类进行多文件代码输出
  outputByCategory: false,
  // 生成的目标代码类型。默认: typescript
  target: 'typescript',
  // request请求工具函数文件路径。
  requestFunctionFilePath: 'src/utils/request.ts',
  // 生成只包含这些分类的接口
  includeCategory: ['pet'],
  // 接口文档服务配置
  documentServers: [{
    // 文档地址【当type为'swagger'类型时，可以读取本地文件，这里就可以一个本地文件路径】
    url: 'https://petstore.swagger.io/v2/swagger.json',
    // 文档类型，根据文档类型，调用内置的解析器，默认值: 'swagger'【内置yapi和swagger的解析，其他文档类型，添加parserPlugins自行实现文档解析】
    type: 'swagger',
    // 访问文档可能需要认证信息，http auth 验证方式
    // auth: {
    //   username: 'username',
    //   password: 'password',
    // },
  }],
});

转化生成的pet.ts文件部分代码如下

/**
 * @description Deletes a pet
 * @summary Request data types
 * @url [ DELETE ] /v2/pet/{petId}
 */
export interface V2PetPetIdRequestByDelete {
  // Pet id to delete
  petId: string;
}
/**
 * @description Deletes a pet
 * @summary Response data types
 * @url [ DELETE ] /v2/pet/{petId}
 */
export type V2PetPetIdResponseByDelete = any;
/**
 * @description Deletes a pet
 * @url [ DELETE ] /v2/pet/{petId}
 */
export function v2PetPetIdByDelete(data: V2PetPetIdRequestByDelete, extraData?: unknown, ...args: CurrentRequestFunctionRestArgsType) {
  return request<V2PetPetIdResponseByDelete>(processRequestFunctionConfig(data, extraData, v2PetPetIdByDelete.requestConfig), ...args);
}
v2PetPetIdByDelete.requestConfig = {
  path: '/v2/pet/{petId}',
  method: 'DELETE',
  requestContentType: [],
  formDataKeyNameList: [],
  pathParamKeyNameList: ['petId'],
  queryStringKeyNameList: [],
};

但这类库无法直接在项目里用，主要原因是：

就算指定了request请求，但是输出调用结构上还是axios的传参结构，不太符合原有项目封装的request调用方式
每次生成文件都是覆盖式的，之前的修改都会被覆盖掉
生成的ts类不够好：会有重复的部分、不会使用/提取公共类、不会生成枚举，这些都需要人为调整优化

虽然其无法直接应用到项目中，但是还是有用的：比起一条条复制粘贴再转化ts了，直接用该库生成ts后，再选择性复制粘贴到项目里，会稍稍方便些，且转化的ts类型字段有注释

# 其他

其他类似的转化ts工具还有很多很多

第三方库有：@umijs/openapi (opens new window)、openapi-ts (opens new window) 等等，这些用的人也不少。

在线转化：

apifox (opens new window)：可以导入url后，找到相应请求，可以生成ts代码及注释。用这个在线工具更适合单个请求转化，第三方库更适合相同类别多个请求一次性转化**（后发现可以通过mcp一次性获取多个接口，见下文）**

swagger在线编辑器 (opens new window)，swagger官方编辑器，用法可参考博客 (opens new window)，不过我尝试导入url并没有成功就没再用了

# 直接用AI来做

因为就算用第三方库转化ts方便些了，还是需要人为复制粘贴，然后改成和原项目相同风格的代码，这些重复简单的工作，就希望能借助AI完成

开始是想用扣子，LinkReaderPlugin插件读取swagger链接。

尝试提供内容少的swagger文档 (opens new window)，能成功读取并转化返回ts

但是用到实际开发的文档，因为文档内容很多，就算是跟AI指定了tags，也会因为文档太大，读取被截断，无法完整读取链接内容，在第一步读取文档就失败了

# 第三方库+AI

由于AI很难解析复杂的、内容多的swagger文档，文档太大就算指定的tags，也解析不出来，尝试过扣子、Tace、Cursor等都解析不了

但是使用如api-helper的第三方库指定了tags，转化很快，只是转化的ts内容格式和我们项目的格式不太符合，所以可以通过第三方库转化ts，AI再处理和优化的方式：

首先手动配置第三方库的配置文件、执行命令行输出ts文件；

其次让AI根据该ts文件和项目其他接口的写法，生成符合原项目代码风格的代码到相应位置，最重要的就是描述准确，不符合的增加描述让AI调整（注意和AI强调找不到相应接口就不生成，否则他会给你编造接口和ts类型的）。

最后再人为核对，调整细节即可。

AI的选择：用过通义灵码、copilot等，但都还是需人为调整。目前发现转化最准确、需人为调整最少的是Cursor，其阅读上下文的能力很强。不过Cursor需付费使用。

第三方库的选择：如上文的介绍都可，不过本人用的比较多的是api-helper

参考步骤：

修改apih.config.js配置
运行pnpm apih转化ts
让AI根据转化的ts文件处理优化，给AI的参考指令如下，下划线内容根据实际调整，注意事项也是根据自己项目要求修改：（这一步也可用定义rules来省略指令，可参考下一个方法）

请根据已生成的 pet.ts 文件，提取上传图片、删除这些接口到 apiConfig.ts文件和petMng.ts文件的相应位置。注意：1.未找到对应的接口，不要自己编造生成，直接跳过或中断即可；2.提取接口不是照搬，需参考项目中其他接口ts的写法；3.不要重复生成相同的interface、需使用公共interface、有枚举也生成相应的enum枚举；4.还需要相关注释，其中注释格式用/** */单行注释表示，注意是单行，不是多行。
人工核对并调整

# 通过 MCP 使用 Apifox 项目内的 API 文档

最新发现通过MCP获取文档最方便，不需要第三方库转化ts了，配置好后，基本都是由AI做了。不过若是文档比较大，MCP获取文档速度会很慢，且消耗AI token比较多，比较费钱..一次性获取较多文档时比较适用

首先是要创建Apifox项目，并导入了API文档，接口文档加密也可导入，配置用户名和密码即可

然后配置MCP，具体过程可看文档通过 MCP 使用 Apifox 项目内的 API 文档 (opens new window)

如果接口文档没有加密，可以直接使用 OpenAPI/Swagger 文档链接配置，就不一定要创建Apifox项目了。详见通过 MCP 使用 OpenAPI/Swagger 文档 (opens new window)

另外推荐搭配相应的rules，让转化后的ts更符合项目风格，rule也可以让AI生成的

最后配置好后，对话框输入 “请通过 MCP 获取 API 文档，提取 {target-apis} 这些接口到 apiConfig.ts 文件和 {target-files} 文件的相应位置” ，再引用规则即可（虽然规则可以设置智能使用，但有时不太智能没应用规则，生成的ts不符合项目风格，又得重新生成，浪费token，所以还是推荐手动指定）

alt text

nys013主页

Choose mode