@magicbe/api-generator/README.md

api 生成器

# @magicbe/api-generator

一个强大的 API 代码生成器，支持从 YApi 和 Swagger 自动生成 TypeScript/JavaScript 接口定义和请求函数。

## ✨ 核心特性

- **🚀 多平台支持**: 支持 YApi 和 Swagger/OpenAPI 两大主流 API 管理平台
- **🔒 类型安全**: 自动生成完整的 TypeScript 接口定义，确保类型安全
- **🎯 智能命名**: 自动处理接口命名，支持驼峰命名转换和特殊字符处理
- **📦 嵌套接口**: 智能生成嵌套接口，保持代码结构清晰
- **🔧 特殊字符处理**: 正确处理以数字开头的属性名（使用引号包裹）
- **📋 代码格式化**: 使用 Prettier 自动格式化生成的代码
- **⚙️ 灵活配置**: 支持配置文件和命令行参数两种方式
- **📖 帮助系统**: 内置完整的帮助文档 (`--help` / `-h`)

## 🚀 快速开始

### 安装

```bash
# 全局安装
npm install -g @magicbe/api-generator
# 或
yarn global add @magicbe/api-generator
# 或
pnpm add -g @magicbe/api-generator
```

### 基本使用

#### 方法 1: 使用配置文件

创建 `api-generator.config.json` 文件：

```json
{
  "type": "yapi",
  "service": "https://your-yapi-domain.com",
  "token": "your-api-token",
  "output": "./src/api",
  "target": "typescript"
}
```

运行命令：

```bash
gen-api
```

#### 方法 2: 使用命令行参数

```bash
gen-api --type yapi --service https://your-yapi-domain.com --token your-api-token --output ./src/api --target typescript
```

#### 方法 3: 查看帮助

```bash
gen-api --help
# 或
gen-api -h
```

## 📋 配置参数

### 命令行参数

| 参数 | 类型 | 说明 | 必填 |
|------|------|------|------|
| `--type` | string | API 平台类型: `yapi` \| `swagger` | ✅ |
| `--service` | string | API 服务地址 | ✅ |
| `--output` | string | 输出目录路径 | ✅ |
| `--target` | string | 目标语言: `typescript` \| `javascript` | ✅ |
| `--token` | string | YApi 访问令牌 (YApi 需要) | ❌ |
| `--cats` | string | YApi 分类 ID，多个用逗号分隔 (YApi 可选) | ❌ |
| `--resources` | string | Swagger 资源名称，多个用逗号分隔 (Swagger 可选) | ❌ |
| `--function` | string | 请求函数导入路径 (可选，默认: `@/request`) | ❌ |
| `--headers` | string | 自定义请求头，JSON 格式 (Swagger 可选) | ❌ |
| `--config` | string | 配置文件路径 (可选，默认: `./api-generator.config.json`) | ❌ |
| `--help, -h` | - | 显示帮助信息 | ❌ |

### 配置文件格式

```json
{
  "type": "yapi",
  "service": "https://your-yapi-domain.com",
  "token": "your-api-token",
  "output": "./src/api",
  "target": "typescript",
  "function": "@/utils/request",
  "cats": [123, 456],
}
```

## 🏗️ 生成的代码结构

### 接口定义示例

```typescript
/** 用户列表 请求参数 */
export interface GetUserListQuery {
  page: number;
  page_size: number;
  keyword?: string;
}

/** 用户列表 响应数据 */
export interface GetUserListResponseData {
  total: number;
  items: GetUserListResponseDataItems[];
}

/** 用户列表 响应主体 */
export interface GetUserListResponse {
  code: number;
  msg: string;
  data: GetUserListResponseData;
}
```

### 请求函数示例

```typescript
/**
 * 用户列表
 * https://yapi.example.com/project/123/interface/api/456
 */
export const getUserList = (query: GetUserListQuery) => 
  request.get<GetUserListResponse>('/user/list', { params: query });
```

## 🎯 智能特性详解

### 1. 智能接口命名

- **路径转换**: 自动将 API 路径转换为驼峰命名
- **HTTP 方法前缀**: 根据请求方法添加前缀 (`get`, `post`, `put`, `delete`)
- **参数处理**: 智能处理路径参数和查询参数

### 2. 嵌套接口生成

- **层次结构**: 自动识别嵌套对象结构
- **命名规则**: 使用 "当前接口名 + Key(首字母大写)" 的命名方式
- **递归处理**: 支持多层嵌套结构的递归生成

### 3. 特殊字符处理

- **数字开头属性**: 自动使用引号包裹 (如 `"0558d78b39cf4824b57b56047a8d47fc": string`)
- **命名转换**: 支持下划线、连字符等转换为驼峰命名
- **语法合规**: 确保生成的 TypeScript 代码完全符合语法规范

### 4. 类型安全增强

- **完整类型定义**: 为所有接口生成完整的 TypeScript 类型
- **可选/必填区分**: 正确识别可选参数和必填参数
- **响应数据类型**: 为响应数据提供完整的类型约束

## 📦 项目集成

### 1. 安装依赖

```bash
npm install axios
```

### 2. 配置请求实例

创建 `src/request.ts`：

```typescript
import axios from 'axios';

const request = axios.create({
  baseURL: process.env.VUE_APP_API_BASE_URL,
  timeout: 10000,
});

// 请求拦截器
request.interceptors.request.use(
  config => {
    // 添加认证头等逻辑
    return config;
  },
  error => {
    return Promise.reject(error);
  }
);

// 响应拦截器
request.interceptors.response.use(
  response => {
    return response.data;
  },
  error => {
    // 统一错误处理
    return Promise.reject(error);
  }
);

export default request;
```

### 3. 使用生成的 API

```typescript
import { getUserList } from '@/api/gen_api_123';

// 使用 API
const loadUsers = async () => {
  try {
    const response = await getUserList({
      page: 1,
      page_size: 10,
      keyword: 'search'
    });
    console.log(response.data);
  } catch (error) {
    console.error('加载用户列表失败:', error);
  }
};
```

## 🔧 高级用法

### YApi 分类过滤

只生成指定分类的 API：

```bash
gen-api --type yapi --service https://yapi.example.com --token your-token --output ./src/api --target typescript --cats 123,456
```

### Swagger 多资源

同时处理多个 Swagger 资源：

```bash
gen-api --type swagger --service https://swagger.example.com/swagger.json --output ./src/api --target typescript --resources user,order
```

### 自定义函数命名

```bash
gen-api --type yapi --service https://yapi.example.com --token your-token --output ./src/api --target typescript --function @/utils/custom-request
```

## 🛠️ 开发指南

### 本地开发

```bash
# 克隆项目
git clone https://github.com/your-org/api-generator.git

# 安装依赖
pnpm install

# 开发模式
pnpm dev

# 构建项目
pnpm build
```

### 项目结构

```
src/
├── Generator.ts              # 基础生成器类
├── GeneratorYapi.ts          # YApi 生成器基类
├── GeneratorSwaggerApi.ts    # Swagger 生成器
├── library.ts                # 命令行工具入口
├── help.txt                  # 帮助文档
└── index.ts                  # 主入口文件
```

### 构建脚本

- `pnpm dev`: 使用 nodemon 进行开发
- `pnpm build`: 构建 TypeScript 项目并复制帮助文件
- `pnpm lint`: ESLint 代码检查

## 🎨 代码示例

### 生成的复杂接口示例

```typescript
/** 报表详情 响应数据 */
export interface GetAdminReportDetailResponse {
  code: number;
  msg: string;
  data: GetAdminReportDetailResponseData;
}

/** 报表详情 数据内容 */
export interface GetAdminReportDetailResponseData {
  period_map: GetAdminReportDetailResponsePeriodMap;
  total_count: number;
  items: GetAdminReportDetailResponseDataItems[];
}

/** 报表详情 时间段映射 */
export interface GetAdminReportDetailResponsePeriodMap {
  [key: string]: string;
}

/** 报表详情 项目列表 */
export interface GetAdminReportDetailResponseDataItems {
  id: number;
  name: string;
  status: number;
  "0558d78b39cf4824b57b56047a8d47fc": string; // 特殊字符处理示例
}
```

### 生成的请求函数示例

```typescript
/**
 * 获取报表详情
 * https://yapi.example.com/project/123/interface/api/789
 */
export const getAdminReportDetail = (query: GetAdminReportDetailQuery) => 
  request.get<GetAdminReportDetailResponse>('/admin/report/detail', { params: query });
```

## 🤝 贡献指南

欢迎提交 Issue 和 Pull Request！

### 提交规范

- 使用清晰的提交信息
- 添加适当的测试用例
- 更新相关文档
- 遵循代码风格规范

## 📄 许可证

MIT License

## 🆘 支持与联系

如有问题，请通过以下方式联系：

- 📧 邮箱：304587090@qq.com
- 🌐 项目主页：[http://www.wangquan.top](http://www.wangquan.top)
- 📚 文档：参见项目 README.md

---

<div align="center">

**🎉 Happy Coding!**

如果你觉得这个项目有帮助，请给个 ⭐️ 支持一下！

</div>