@scx/api-tool

一个强大的 Node.js CLI 工具，专门用于从各种 API 管理平台（如 Swagger/OpenAPI 3.0、Apifox）自动生成 TypeScript/JavaScript 代码。

主要特性

• 多平台支持: 支持 Swagger、Apifox 等主流 API 管理平台
• 类型生成: 自动生成完整的 TypeScript 类型定义，支持 TypeScript 和 Zod 两种模式
• 代码生成: 自动生成 HTTP 请求函数和接口代码
• 路径参数插值: 自动将 OpenAPI 路径中的 {param} 占位符插值为模板字符串（如 `/api/stock/${params.code}`），支持多参数与安全转义
• 灵活配置: 支持自定义命名策略、输出目录、代码风格等
• 钩子系统: 在代码生成过程的不同阶段执行自定义操作
• Watch 模式: 监视配置文件变化，自动重新生成代码

快速开始

安装

# 全局安装（推荐）
pnpm install -g @scxfe/api-tool

# 或项目本地安装
pnpm install --save-dev @scxfe/api-tool

# 或使用 npx
npx @scxfe/api-tool

基本使用

# 1. 初始化配置文件
npx api-power init

# 2. 编辑配置文件 api-power.config.ts / api-power.config.js

# 3. 生成代码
npx api-power

文档

• CLI 工具介绍 - 工具介绍和安装说明
• CLI 使用说明 - 详细的使用方法和命令说明
• 配置指南 - 完整的配置项说明和示例
• 高级用法 - 自定义命名策略、钩子系统、Watch 模式等
• 使用示例 - 完整的使用示例和代码生成展示

配置示例

defineConfig 采用多服务（microservice）配置：所有服务共享公共配置（如 typesFormat、baseOutputDir、namingStrategy），每个服务在 services 数组中声明自己的数据源和输出位置。返回值为 ApiConfig[]，单源即数组长度为 1。

单服务 - Zod 模式（运行时验证）

import { defineConfig } from '@scxfe/api-tool';

export default defineConfig({
  // 公共配置：所有服务继承
  baseOutputDir: 'src/service', // 公共根输出目录（原 outputDir 改名）
  typesFormat: 'zod', // 使用 Zod Schema 进行类型定义和运行时验证
  generateApi: true,
  generateTypes: true,

  services: [
    {
      name: 'main', // 服务名（唯一），默认 folder 取 name
      folder: '.', // 输出直接落在 baseOutputDir，等价于单源旧配置
      source: 'https://api.apifox.com/v1/projects/YOUR_PROJECT_ID/export-openapi',
      token: 'YOUR_ACCESS_TOKEN',
    },
  ],
});

单服务 - TypeScript 模式（编译时类型检查）

import { defineConfig } from '@scxfe/api-tool';

export default defineConfig({
  baseOutputDir: 'src/service',
  typesFormat: 'typescript', // 使用 TypeScript 接口进行类型定义
  generateApi: true,
  generateTypes: true,

  services: [
    {
      name: 'main',
      folder: '.',
      source: 'https://api.apifox.com/v1/projects/YOUR_PROJECT_ID/export-openapi',
      token: 'YOUR_ACCESS_TOKEN',
    },
  ],
});

多服务（微服务）

适合需要同时对接多个后端服务（用户服务、订单服务等）的项目。每个服务有独立的数据源、token 和输出子目录，共享 baseOutputDir 下的 request.ts。

import { defineConfig } from '@scxfe/api-tool';

export default defineConfig({
  baseOutputDir: 'src/service', // 公共根目录：request.ts 在此层级共享
  typesFormat: 'typescript',
  generateApi: true,
  generateTypes: true,

  services: [
    {
      name: 'user',
      source: 'https://user-svc.example.com/v3/api-docs',
      token: 'APS-user-token',
      // folder 省略 → 默认 'user' → 输出 src/service/user
    },
    {
      name: 'order',
      source: 'https://order-svc.example.com/swagger.json',
      token: 'APS-order-token',
      folder: 'trade/order', // 多段 folder → 输出 src/service/trade/order
    },
  ],
});

完整配置

import { defineConfig } from '@scxfe/api-tool';

export default defineConfig({
  // 公共输出根目录
  baseOutputDir: 'src/service',

  // 类型生成格式
  typesFormat: 'zod', // 或 'typescript'

  // 输出配置
  generateApi: true,
  generateTypes: true,

  // 代码生成选项
  target: 'typescript',
  indentSize: 2,
  comment: true,
  transformPath: (p) => '/api/v1' + p,

  // 请求函数配置
  requestFunctionName: 'request',
  requestParamName: 'params',
  requestMethodStyle: 'config',

  // 自定义命名策略
  namingStrategy: {
    interfaceName: (info) => {
      const method = info.method.charAt(0).toUpperCase() + info.method.slice(1).toLowerCase();
      const pathName = info.path
        .replace(/\{[^}]+\}/g, '')
        .replace(/^\//, '')
        .replace(/\//g, '-')
        .replace(/^-+|-+$/g, '');
      return `${method}${pathName}`;
    },
  },

  // 钩子函数
  hooks: {
    beforeGenerate: () => {
      console.log('开始生成代码...');
    },
    afterGenerate: () => {
      console.log('代码生成完成');
    },
  },

  // 服务声明
  services: [
    {
      name: 'main',
      folder: '.',
      source: 'https://api.apifox.com/v1/projects/YOUR_PROJECT_ID/export-openapi',
      token: 'YOUR_ACCESS_TOKEN',
    },
  ],
});

项目结构

输出结构遵循 baseOutputDir/<folder或name>/...。request.ts 位于 baseOutputDir 层级并被各服务共享；每个服务的输出（分类目录、types/schemas、index.ts）落在 join(baseOutputDir, folder ?? name) 下。

单服务输出结构（folder: '.'，输出直接落在 baseOutputDir）

Zod 模式

src/service/                      # baseOutputDir
├── request.ts                    # 共享请求函数（baseOutputDir 层级，永不被 clean）
├── index.ts                      # 根导出文件
├── AIFuWu/                       # 分类目录
│   ├── index.ts                  # API 函数（从 schema 导入类型）
│   └── schema.ts                 # 合并的 Schema 文件（包含所有接口的 Schema + 推导类型）
├── YongHuGuanLi/                 # 分类目录
│   ├── index.ts
│   └── schema.ts
└── schemas/                      # 类型 Schema 目录
    ├── UserSchema.ts             # 类型 Schema（包含 Schema + 推导类型）
    ├── RoleSchema.ts
    └── index.ts                  # Schema 索引文件

TypeScript 模式

src/service/                      # baseOutputDir
├── request.ts                    # 共享请求函数
├── index.ts                      # 根导出文件
├── AIFuWu/                       # 分类目录
│   └── index.ts                  # API 函数
├── YongHuGuanLi/                 # 分类目录
│   └── index.ts
└── types/                        # 类型定义目录
    ├── index.ts                  # 类型索引文件
    ├── User.ts
    └── Role.ts

多服务输出结构（微服务）

src/service/                      # baseOutputDir
├── request.ts                    # 共享请求函数（仅生成一次，所有服务共用）
├── user/                         # join(base, 'user')（folder 默认取 name）
│   ├── index.ts
│   ├── <tag拼音>/index.ts
│   └── types/
└── trade/order/                  # join(base, 'trade/order')（多段 folder）
    ├── index.ts
    ├── <tag拼音>/index.ts
    └── types/

开发

# 安装依赖
pnpm install

# 构建项目
pnpm run build

# 生成代码（开发模式）
pnpm run dev

# 格式化并修复代码
pnpm run lint:fix

# 构建文档
pnpm run docs:build

# 预览构建结果
pnpm run docs:preview

许可证

MIT License - 详见 LICENSE 文件

贡献

欢迎提交 Issue 和 Pull Request！

联系方式

• 作者: shawicx
• 邮箱: [email protected]
• GitHub: @shawicx