yapi-ts-generator

English | 简体中文

yapi-ts-generator 是一个面向 YApi 的命令行生成器。它从 YApi 导出地址读取接口定义，生成 TypeScript 请求/响应类型以及请求函数。

能力

• 生成请求参数、响应类型和类型安全的请求函数
• 支持路径参数、查询参数、JSON Body、Form Body 和固定请求头
• 支持多个 YApi 项目以及按 URL 前缀拆分输出文件
• 支持 URL token、全局 token、账号登录和 HTTPS 客户端证书
• 全局配置完全可选；只提供带 token 的 YApi URL 即可使用
• 生成前完成校验和格式化，写入失败时自动回滚

环境要求

• Node.js 20 或更高版本
• 可访问目标 YApi 服务

npm install --global yapi-ts-generator
ytg --version

最短使用路径：不创建全局配置

在业务项目根目录创建项目配置：

ytg init --project

编辑 .yapi-ts-generator.config.yml：

- yapiUrl: https://yapi.example.com/api/open/plugin/export-full?type=json&pid=1&status=all&token=YOUR_TOKEN
  outputDir: ./src/api

验证连接并生成：

ytg test
ytg create

生成结果默认为：

src/api/
  api.interface.ts  # 请求参数和响应类型
  api.handler.ts    # 调用 request() 的函数

代表性的生成结果如下。路径、查询和 Body 参数会分别进入 URL、params 和 data：

export interface IPostUsersByUserIdParams {
  "user-id": string;
  notify?: boolean;
  displayName: string;
}

export async function postUsersByUserId(
  params: IPostUsersByUserIdParams,
  config?: Record<string, any>,
): Promise<IPostUsersByUserIdResponse> {
  return request(`/api/users/${params["user-id"]}`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    params: { notify: params.notify },
    data: { displayName: params.displayName },
    config: config ?? {},
  });
}

也可以不创建任何配置文件：

ytg quick-create \
  --url "https://yapi.example.com/export?token=YOUR_TOKEN" \
  --output-dir ./src/api \
  --output-file api.ts

可选全局配置

只有以下场景才需要全局配置：

• 不希望把 token 写入项目配置
• 需要通过账号和密码换取 token
• YApi 使用 PFX 客户端证书

ytg init --global

配置位置为 ~/.yapi-ts-generator/config.yml。旧版本拼写错误的 ~/.yapi-ts-genterator/config.yml 仍可读取；两个文件同时存在时优先使用新路径。

命令

| 命令 | 作用 | | -------------------------- | -------------------------- | | ytg init -d, --project | 创建项目配置 | | ytg init -g, --global | 创建可选全局配置 | | ytg config -d, --project | 脱敏显示项目配置 | | ytg config -g, --global | 脱敏显示全局配置 | | ytg test [-e file] | 只验证网络和认证，不写文件 | | ytg create [-e file] | 生成或更新文件 | | ytg create --clean | 成功生成后替换整个输出目录 | | ytg quick-create ... | 不依赖项目配置直接生成 |

--clean 只能操作当前项目内的子目录，不能删除项目根目录或项目外路径。

请求函数约定

生成的 Handler 默认导入：

import { request } from "@/utils/request";

通过 requestImportPath 修改导入路径。每个 Handler 的第二个参数都是可选的 config，并作为 config: config ?? {} 传给 request。生成器不解释该对象，业务侧可以用它实现动态 Header、超时或取消请求。request 函数需要接受 URL 和包含 method、headers、params、data、config 的选项对象，并返回 Promise<T>。

项目维护

• 开发与贡献
• 变更记录

安全提示

YApi token、密码和证书口令都属于敏感信息。CLI 会在日志和 config 命令中脱敏，但项目配置是否进入版本控制由使用方决定。团队项目建议使用全局配置保存凭据，并限制配置文件和 PFX 文件的访问权限。

License

MIT