Apifox Flow - TypeScript 代码生成器

这是一个基于 Rust 的工具，用于从 Apifox 的 OpenAPI 文档自动生成 TypeScript 类型定义和 API 客户端代码。

功能特性

• 🚀 自动从 Apifox 获取 OpenAPI 文档
• 📝 生成完整的 TypeScript 类型定义
• 🔧 生成类型安全的 API 客户端
• 🎯 支持枚举、接口、数组等复杂类型
• 📦 支持可选属性和可空类型
• 🔄 自动处理 API 路径和方法映射
• 📁 按 Apifox 文件夹结构组织代码（新功能）
• 🏗️ 模块化架构，支持按需导入
• 🎨 智能文件夹名称处理（支持中文和特殊字符）
• ⚡ 命令行支持，可指定生成特定文件夹（新功能）
• 📋 列出所有可用文件夹功能
• 🛠️ 完整的错误处理和帮助信息
• 🎨 模板系统支持，可自定义代码生成格式（新功能）
• 🔧 内置多种模板类型（default, advanced, react, oboss）
• 📝 支持自定义模板目录

安装和运行

前置要求

• Rust 1.70+
• Apifox 服务运行在 http://127.0.0.1:4523

基本运行

1. 克隆或下载项目
2. 确保 Apifox 服务正在运行
3. 运行生成器：

# 生成所有代码
cargo run -- generate

# 或者直接运行（默认行为）
cargo run

命令行功能

查看帮助信息

# 查看主帮助
cargo run -- --help

# 查看生成命令帮助
cargo run -- generate --help

列出所有可用的文件夹

cargo run -- list-folders

生成指定文件夹的代码

# 生成 Customer Service 文件夹的代码
cargo run -- generate --folder "Customer Service"

# 生成中文文件夹的代码
cargo run -- generate --folder "公共分类 Public Classification"

# 指定输出目录
cargo run -- generate --folder "Lucky Draw" --output my_api_code

完整参数示例

cargo run -- generate \
  --folder "Customer Service" \
  --output customer_service_api \
  --project-id 162 \
  --base-url http://127.0.0.1:4523

模板系统

使用内置模板

# 使用高级模板（包含超时、重试等高级功能）
cargo run -- generate --template advanced

# 使用 React 模板（生成 React Hooks）
cargo run -- generate --template react

# 使用 Oboss 模板（函数式导出，支持 Mock）
cargo run -- generate --template oboss

# 使用默认模板（传统方式）
cargo run -- generate --template default

使用自定义模板

# 使用自定义模板目录
cargo run -- generate --template-dir my_templates

# 结合文件夹和模板
cargo run -- generate --folder "Customer Service" --template advanced
cargo run -- generate --folder "Lucky Draw" --template oboss

详细的使用说明请参考：

• CLI_USAGE.md - 命令行使用指南
• TEMPLATE_GUIDE.md - 模板系统使用指南

生成的文件

运行后会生成以下文件：

整体文件

• openapi_doc.json - 从 Apifox 获取的原始 OpenAPI 文档
• generated_types.ts - TypeScript 类型定义
• api_client.ts - API 客户端类
• generated_api.ts - 完整的 API 文件（包含类型和客户端）

按文件夹结构生成的文件

• generated_by_folders/ - 按 Apifox 文件夹结构组织的代码目录
  • 每个文件夹包含：
    • api.ts - 该文件夹的 API 客户端
    • types.ts - 该文件夹相关的类型定义
    • index.ts - 该文件夹的导出文件
  • index.ts - 主索引文件，导出所有模块

使用示例

方式1: 使用整体 API 客户端

import { ApiClient } from './api_client';
import { MktTheme, Points, Enum } from './generated_types';

const apiClient = new ApiClient('https://your-api-base-url.com');

// 获取楼层列表
const floors = await apiClient.getFloors({
  location: 'HOME',
  isActive: 'true',
  offset: 0,
  limit: 10
});

方式2: 按文件夹结构使用（推荐）

// 导入特定模块
import { ApiClient as CustomerServiceClient } from './generated_by_folders/customer_service';
import { ApiClient as LuckyDrawClient } from './generated_by_folders/lucky_draw';

// 或者从主索引导入
import { customer_service, lucky_draw } from './generated_by_folders';

// 创建模块化客户端
const customerService = new CustomerServiceClient('https://your-api-base-url.com');
const luckyDraw = new LuckyDrawClient('https://your-api-base-url.com');

// 使用特定模块的 API
const contacts = await customerService.getContact({
  startDate: '2024-01-01',
  endDate: '2024-01-31',
  limit: '20',
  offset: '0'
});

const drawInfo = await luckyDraw.getLuckyDraw({
  id: 'draw-123',
  cookie: 'session-cookie'
});

文件夹结构的优势

1. 模块化开发: 每个功能模块独立，便于团队协作
2. 按需导入: 只导入需要的模块，减少打包体积
3. 清晰的代码组织: 按照业务功能分组，易于维护
4. 类型隔离: 每个模块只包含相关的类型定义
5. 支持中文文件夹: 自动处理中文和特殊字符的文件夹名称

3. 使用类型安全的对象

const theme: MktTheme = {
  components: [],
  createTime: Date.now(),
  id: 'theme-123',
  location: 'LUCKY_DRAW', // 类型安全：只能是 "LUCKY_DRAW" | "MGM"
  name: '我的主题',
  status: 'ENABLED', // 类型安全：只能是 "ENABLED" | "DISABLED" | "DELETED" | "SAVED"
  template: {} as any,
  templateId: 'template-123',
  updateTime: Date.now(),
  validFrom: null,
  validTo: null
};

配置

修改 Apifox 项目 ID

在 src/main.rs 中修改项目 ID：

let api_url = "http://127.0.0.1:4523/export/openapi?projectId=YOUR_PROJECT_ID&specialPurpose=openapi-generator";

自定义生成选项

可以在 typescript_generator.rs 中自定义：

• 类型命名规则
• API 方法命名规则
• 输出格式
• 错误处理

生成的类型特性

枚举类型

export enum SourceEnum {
  BNPL = "BNPL",
  CASH = "CASH",
  CARD = "CARD",
  ATOME = "ATOME",
  SAVINGS = "SAVINGS",
  VA_PAYLATER = "VA_PAYLATER",
  BMI_CARD = "BMI_CARD"
}

接口类型

export interface MktTheme {
  components: ComponentInfo[];
  createTime: number;
  id: string;
  location: "LUCKY_DRAW" | "MGM";
  name: string;
  status: "ENABLED" | "DISABLED" | "DELETED" | "SAVED";
  template: ThemeTemplate;
  templateId: string;
  updateTime: number;
  validFrom: number | null;
  validTo: number | null;
}

API 客户端方法

export class ApiClient {
  // 获取楼层列表
  async getFloors(params: { location?: string, isActive: string, offset?: number, limit?: number, Cookie?: string }): Promise<any>
  
  // 创建楼层
  async createFloors(params: { Cookie?: string, body: any }): Promise<any>
  
  // 更新模块
  async createUpdate(params: { moduleId: string, Content-Type: string, body: any }): Promise<any>
}

注意事项

1. 生成的文件包含自动生成的注释，请勿手动修改
2. 每次运行都会重新生成所有文件
3. 确保 Apifox 服务正在运行且可访问
4. 生成的类型定义基于 OpenAPI 3.0 规范

故障排除

常见问题

1. 连接 Apifox 失败

   • 确保 Apifox 服务运行在 http://127.0.0.1:4523
   • 检查项目 ID 是否正确

2. 编译错误

   • 确保 Rust 版本 >= 1.70
   • 运行 cargo clean && cargo build 清理缓存

3. 生成的类型不完整

   • 检查 OpenAPI 文档是否完整
   • 查看 openapi_doc.json 文件内容

贡献

欢迎提交 Issue 和 Pull Request 来改进这个工具！

许可证

MIT License