# 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. 运行生成器：

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

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

### 命令行功能

#### 查看帮助信息
```bash
# 查看主帮助
cargo run -- --help

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

#### 列出所有可用的文件夹
```bash
cargo run -- list-folders
```

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

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

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

#### 完整参数示例
```bash
cargo run -- generate \
  --folder "Customer Service" \
  --output customer_service_api \
  --project-id 162 \
  --base-url http://127.0.0.1:4523
```

### 模板系统

#### 使用内置模板
```bash
# 使用高级模板（包含超时、重试等高级功能）
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
```

#### 使用自定义模板
```bash
# 使用自定义模板目录
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](./CLI_USAGE.md) - 命令行使用指南
- [TEMPLATE_GUIDE.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 客户端

```typescript
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: 按文件夹结构使用（推荐）

```typescript
// 导入特定模块
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. 使用类型安全的对象

```typescript
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：

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

### 自定义生成选项

可以在 `typescript_generator.rs` 中自定义：

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

## 生成的类型特性

### 枚举类型

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

### 接口类型

```typescript
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 客户端方法

```typescript
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
