hookehuyr

docs(api-generator): 添加 OpenAPI 转 API 生成器快速开始指南

## 新增
- scripts/api-generator/QUICKSTART.md
  - 一分钟快速上手教程
  - 常见场景示例
  - 配置和自定义说明
  - 调试技巧

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
# OpenAPI 转 API 文档生成器 - 快速开始
## 🎯 一分钟快速上手
### 1️⃣ 创建 OpenAPI 文档
`docs/api-specs/` 目录下创建模块和接口文档:
```bash
# 创建新模块
mkdir -p docs/api-specs/product
# 创建接口文档
touch docs/api-specs/product/getList.md
```
### 2️⃣ 编写 OpenAPI 规范
编辑 `getList.md`
```markdown
# 获取商品列表
## OpenAPI Specification
\```yaml
openapi: 3.0.1
info:
title: ''
version: 1.0.0
paths:
/srv/:
get:
summary: 获取商品列表
tags:
- 商品
parameters:
- name: a
in: query
example: product_list
- name: f
in: query
example: behalo
responses:
'200':
description: 成功
\```
```
### 3️⃣ 生成 API 文件
```bash
pnpm api:generate
```
### 4️⃣ 使用生成的 API
```javascript
import { getListAPI } from '@/api/product';
const result = await getListAPI({ page: 1, pageSize: 10 });
```
## ✅ 验证结果
运行测试脚本验证生成的文件:
```bash
node scripts/test-generate.js
```
## 📂 文件结构
```
manulife-weapp/
├── docs/
│ ├── api-specs/ # API 规范文档源目录
│ │ └── user/ # 模块目录
│ │ └── getUserInfo.md
│ ├── OPENAPI_TO_API_GUIDE.md # 详细使用指南
│ └── API_USAGE_EXAMPLES.md # API 使用示例
├── scripts/
│ ├── generateApiFromOpenAPI.js # 生成器核心脚本
│ └── test-generate.js # 测试脚本
├── src/
│ └── api/ # 生成的 API 文件目录
│ ├── user.js # 自动生成
│ ├── wx/
│ └── index.js
└── package.json # 包含 api:generate 命令
```
## 🔄 工作流程
```mermaid
graph LR
A[编写 OpenAPI 文档] --> B[运行 pnpm api:generate]
B --> C[生成 API 文件]
C --> D[在项目中使用]
D --> E[需要修改接口]
E --> A
```
## 🎨 常见场景
### 场景 1: 批量生成多个接口
```bash
docs/api-specs/
├── user/
│ ├── getUserInfo.md
│ ├── updateProfile.md
│ └── changePassword.md
└── order/
├── getList.md
└── getDetail.md
```
运行 `pnpm api:generate` 后生成:
```
src/api/
├── user.js # 包含 3 个接口
└── order.js # 包含 2 个接口
```
### 场景 2: 更新已有接口
1. 修改 `docs/api-specs/user/getUserInfo.md`
2. 运行 `pnpm api:generate`
3. `src/api/user.js` 自动更新
### 场景 3: 添加新模块
1. 创建 `docs/api-specs/payment/`
2. 添加接口文档
3. 运行生成命令
4. 自动生成 `src/api/payment.js`
## ⚙️ 配置和自定义
### 修改输出目录
编辑 `scripts/generateApiFromOpenAPI.js`
```javascript
const outputDir = path.resolve(__dirname, '../src/api');
// 改为你想要的目录
const outputDir = path.resolve(__dirname, '../src/apis');
```
### 修改命名规则
编辑 `toCamelCase()``toPascalCase()` 函数。
### 修改生成模板
编辑 `generateApiFileContent()` 函数。
## 🐛 调试技巧
### 启用详细日志
在脚本中添加更多 console.log:
```javascript
console.log('解析的 API 信息:', JSON.stringify(apiInfo, null, 2));
```
### 单独测试某个模块
修改脚本中的模块过滤逻辑。
### 查看生成的中间数据
添加调试输出查看 YAML 解析结果。
## 📞 获取帮助
- 详细指南:[OpenAPI 转 API 文档生成器指南](./OPENAPI_TO_API_GUIDE.md)
- 使用示例:[API 使用示例](./API_USAGE_EXAMPLES.md)
- 项目架构:[CLAUDE.md](../CLAUDE.md)
## 🎉 开始使用
现在你已经准备好了!开始创建你的第一个 OpenAPI 文档吧。
```bash
# 1. 创建模块目录
mkdir -p docs/api-specs/your-module
# 2. 创建接口文档(参考 docs/api-specs/user/getUserInfo.md)
# 3. 生成 API
pnpm api:generate
# 4. 查看生成的文件
cat src/api/your-module.js
# 5. 开始使用
```
祝你编码愉快!🚀