OpenAPI 转 API 文档生成器 - 快速开始

🎯 一分钟快速上手

1️⃣ 创建 OpenAPI 文档

在 docs/api-specs/ 目录下创建模块和接口文档：

# 创建新模块
mkdir -p docs/api-specs/product

# 创建接口文档
touch docs/api-specs/product/getList.md

2️⃣ 编写 OpenAPI 规范

编辑 getList.md：

# 获取商品列表

## 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 文件

pnpm api:generate

4️⃣ 使用生成的 API

import { getListAPI } from '@/api/product';

const result = await getListAPI({ page: 1, pageSize: 10 });

✅ 验证结果

运行测试脚本验证生成的文件：

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 命令

🔄 工作流程

graph LR
    A[编写 OpenAPI 文档] --> B[运行 pnpm api:generate]
    B --> C[生成 API 文件]
    C --> D[在项目中使用]
    D --> E[需要修改接口]
    E --> A

🎨 常见场景

场景 1: 批量生成多个接口

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：

const outputDir = path.resolve(__dirname, '../src/api');
// 改为你想要的目录
const outputDir = path.resolve(__dirname, '../src/apis');

修改命名规则

编辑 toCamelCase() 或 toPascalCase() 函数。

修改生成模板

编辑 generateApiFileContent() 函数。

🐛 调试技巧

启用详细日志

在脚本中添加更多 console.log：

console.log('解析的 API 信息:', JSON.stringify(apiInfo, null, 2));

单独测试某个模块

修改脚本中的模块过滤逻辑。

查看生成的中间数据

添加调试输出查看 YAML 解析结果。

📞 获取帮助

• 详细指南：OpenAPI 转 API 文档生成器指南
• 使用示例：API 使用示例
• 项目架构：CLAUDE.md

🎉 开始使用

现在你已经准备好了！开始创建你的第一个 OpenAPI 文档吧。

# 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. 开始使用

祝你编码愉快！🚀