Apifox TS SDK CLI

一个基于 Apifox OpenAPI 定义生成 TypeScript 类型定义和 Axios 服务调用的 CLI 工具。

功能特性

• TypeScript 定义生成：自动生成严格的请求（Request）和响应（Response）Type 接口，确保每一层数据都有类型提示。
• Service 层生成：生成强类型的 API 方法，自动绑定对应的接口定义。
• 中间件模式的 Request 类：提供基于 Axios 封装的 Request 类，支持 Token 注入、错误统一处理、Response 结构自动解包等。
• 通用适配：支持 OpenAPI 3.0 及 Swagger 2.0。

安装

yarn add apifox-ts-sdk -D
# 或
npm install apifox-ts-sdk --save-dev

快速使用

1. 初始化

npx apifox-ts init

2. 配置

编辑 apifox.config.js：

export default {
    /** 你的 OpenAPI JSON 地址 */
    schemaPath: 'http://127.0.0.1:4523/export/openapi', 
    /** 生成目录 */
    outputDir: './src/services',
    /** 引用路径 (默认指向生成的 request.ts) */
    requestInstancePath: '@/services/request', 
};

3. 生成

npx apifox-ts generate

进阶使用指南

处理统一响应结构 (Wrapper)

如果你的后端接口返回统一结构，例如 { code: 0, data: T, msg: string }，生成的 UserRes 类型也会包含这一层。 有两种处理方案：

方案一：在拦截器解包 (推荐) 你可以在 main.ts 中配置 Response 拦截器，直接返回 res.data 或 res.data.data。

import request from '@/services/request';

// Response 拦截器
request.useResponseInterceptor(
  (response) => {
    // 假设后端返回 { code: 0, data: ... }
    const res = response.data;
    if (res.code !== 0) {
        // 处理业务错误
        return Promise.reject(new Error(res.msg));
    }
    // 直接返回业务数据 data，这样前端通过 await getUser() 拿到的就是直接的数据
    return res.data; 
  },
  (error) => Promise.reject(error)
);

注意: 如果你做了上述解包，生成的 UserRes 类型可能还会包裹一层 code/msg。这是因为 Generator 是根据 Swagger 定义生成的。 TypeScript 本身是鸭子类型，通常只要字段对在就行。如果你希望 TS 类型也完美匹配解包后的结构，你需要确认 Apifox 里的 "Response" 定义是否包含了外层。如果包含了，SDK 就会生成外层。

自定义 Request

生成的 request.ts 足够灵活，你可以直接修改它，或者在配置里指定 requestInstancePath 使用你自己的封装。

关于 Definitions

如果你的 src/services/api-interface/definitions.ts 是空的，说明你的 Apifox 项目中没有定义"公共数据模型"(Schemas)，但这不影响使用，参数和返回值类型依然会生成在 API 文件里。