apipost-gen/README.md

A powerful CLI tool for generating API functions from YAPI/APIPost documentation

# apipost-gen

一个强大的 API 代码生成工具，支持从 APIPost 和 Swagger/OpenAPI 文档自动生成 JavaScript API 函数。

## 特性

- 🚀 支持 APIPost 和 Swagger/OpenAPI 3.x 平台
- 📁 智能的URL层级分组和目录结构
- 🎯 简洁的函数命名策略
- 📄 导出结构化的 JSON 数据文件
- 🔧 零配置快速上手

## 安装

```bash
npm install -g apipost-gen
```

## 使用方法

### 快速开始

```bash
api-gen
```

首次运行会引导您选择API平台（APIPost 或 Swagger/OpenAPI）并创建配置文件。

### 平台选择

工具支持两种API文档平台：

1. **APIPost**: 传统的APIPost平台
2. **Swagger/OpenAPI**: 支持OpenAPI 3.x规范的Swagger文档

### 配置文件示例

#### APIPost 配置

创建/修改 `api-gen.config.json`：

```json
{
  "platform": "apipost",
  "token": "your-api-token",
  "projectId": "your-project-id",
  "baseUrl": "https://open.apipost.net/open/apis/list"
}
```

#### Swagger 配置

```json
{
  "platform": "swagger",
  "baseUrl": "http://your-api-server.com/api-docs"
}
```

### 配置参数

- `platform`: API平台类型（`apipost` 或 `swagger`）
- `baseUrl`: API文档地址
- `token`: 项目访问令牌（仅APIPost需要）
- `projectId`: 项目ID（仅APIPost需要）


## 生成的代码示例

### 智能分组和命名

工具会根据URL层级智能分组，生成简洁的函数名：

```javascript
import request from "@/request"
/**
 * 用户登录
 * @method POST
 * @path /admin-api/system/auth/login
 */
export async function postAuthLogin(params) {
  return request({
    url: '/admin-api/system/auth/login',
    method: 'post',
    data: params,
  });
}
```


### 命名规则

**核心原则：HTTP方法始终放在函数名最前面，确保函数名唯一性和可读性**

#### 函数名生成规则
- **格式**：`{HTTP方法}{驼峰命名的路径}`
- **HTTP方法**：get、post、put、delete等（小写）
- **路径转换**：连字符和下划线转换为驼峰命名法，每个单词首字母大写

#### 不同URL模式的处理

**1. RESTful风格URL** (`/user`)：
- GET `/user` → `getUser`
- POST `/user` → `postUser`
- PUT `/user` → `putUser`
- DELETE `/user` → `deleteUser`

**2. 动作式URL** (`/user/get`)：
- GET `/user/get` → `getUserGet`
- POST `/user/create` → `postUserCreate`

**3. 多层级URL** (`/admin-api/system/dept/create`)：
- POST `/admin-api/system/dept/create` → `postDeptCreate`
- GET `/admin-api/system/area/get-by-ip` → `getAreaGetByIp`

#### 为什么HTTP方法在前？

1. **避免重复**：防止 `/user` (GET) 和 `/user/get` (GET) 生成相同的函数名
2. **通用兼容**：支持各种API设计风格（RESTful、动作式、混合式）
3. **语义清晰**：一眼就能看出HTTP方法和操作意图
4. **函数唯一性**：确保不同URL模式下的函数名不会冲突

#### 特殊字符处理
- 连字符(`-`)和下划线(`_`)自动转换为驼峰命名法
- 确保生成的函数名符合JavaScript标识符规范

## 更新日志

### v2.1.1
- 🎯 **重大改进**：函数命名规则优化，HTTP方法前置
- ✨ 支持驼峰命名法，连字符和下划线自动转换
- 🔧 解决不同URL模式下的函数名冲突问题
- 📝 完善命名规则文档，增加详细说明和示例

### v2.1.0
- 🔧 修复URL层级分组逻辑，保持完整的URL层级结构
- 📁 去掉 `function` 目录，直接输出到 `api-gen/`
- 🎯 优化函数命名：倒数第二层作为文件名，最后一层作为函数名
- ✨ 支持APIPost和Swagger的统一分组逻辑
- 📝 更新README文档，修正命名规则说明

### v2.0.7
- 🔧 统一配置文件格式，所有平台都使用 `baseUrl` 字段
- 📝 大幅简化配置，移除所有内部配置字段（`output`、`targetLanguage`）
- 🎯 固定输出到 `api-gen` 目录，固定生成 JavaScript 代码
- ✨ 新增 Swagger/OpenAPI 3.x 支持
- 🎯 优化函数命名策略，生成更简洁的函数名
- 📁 改进URL层级分组逻辑，支持智能目录结构
- 🔧 增强错误处理，提升稳定性

### v2.0.4
- 🚀 支持 APIPost 平台
- 📄 导出结构化 JSON 数据文件
- 🎯 零配置快速上手

## 许可证

MIT

## 作者

kevin