OpenAPI 转 API 文档生成器

📖 功能说明

这是一个自动化工具，可以从 docs/api-specs 目录读取 OpenAPI 规范的 Markdown 文档，自动生成标准化的 JavaScript API 接口文件到 src/api/ 目录。

📁 目录结构

输入目录结构

docs/api-specs/
├── 模块名1/
│   ├── 接口名1.md
│   ├── 接口名2.md
│   └── ...
└── 模块名2/
    └── 接口名3.md

输出目录结构

src/api/
├── 模块名1.js      (自动生成)
├── 模块名2.js      (自动生成)
└── ...

📝 OpenAPI 文档格式

每个 .md 文件需要包含 OpenAPI 3.x YAML 规范。参考格式：

# 接口标题

## OpenAPI Specification

\```yaml
openapi: 3.0.1
info:
  title: ''
  version: 1.0.0
paths:
  /srv/:
    get:  # 或 post
      summary: 接口描述
      description: 详细描述
      tags:
        - 模块名
      parameters:
        - name: a
          in: query
          example: action_name  # 提取为接口的 action
          schema:
            type: string
        - name: f
          in: query
          example: behalo
          schema:
            type: string
        - name: page
          in: query
          description: 页码
          required: false
          example: 1
          schema:
            type: integer
      responses:
        '200':
          description: 成功响应
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    description: 0=失败，1=成功
                  msg:
                    type: string
                    description: 错误信息
                  data:
                    type: object
                    properties:
                      user:
                        type: object
                        properties:
                          id:
                            type: integer
                            description: 用户ID
                          name:
                            type: string
                            description: 姓名
                      list:
                        type: array
                        items:
                          type: object
                          properties:
                            id:
                              type: integer
                              description: ID
                            title:
                              type: string
                              description: 标题
\```

🔑 关键字段说明

生成器会从 OpenAPI 文档中提取以下信息：

字段	说明	示例
summary	接口描述，用于 JSDoc 注释	"查询我的信息"
parameters[].name='a'	GET 请求的 action 参数	user_info
requestBody.properties.a	POST 请求的 action 参数	user_edit
parameters[].in='query'	GET 请求的查询参数	page, pageSize
requestBody	POST 请求的 body 参数	name, avatar
parameters[].in='header'	Header 参数（自动过滤）	不显示在 JSDoc
get / post	HTTP 方法	决定使用 fetch.get 或 fetch.post
responses['200'].schema	响应数据结构	用于生成 JSDoc @returns
description	字段描述	用于生成详细注释
文件名	API 函数名的基础	getUserInfo.md → getUserInfoAPI()

📌 JSDoc 注释生成规则

GET 请求参数注释（@param）

• 从 parameters 中提取 in: query 的参数
• 过滤掉 a、f 参数和 in: header 的参数
• 提取参数名、类型、描述
• 标记必填/可选状态

POST 请求参数注释（@param）

• 从 requestBody 中提取参数
• 过滤掉 a、f 参数
• 过滤掉 in: header 的参数
• 提取参数名、类型、描述
• 标记必填/可选状态

返回值注释（@returns）

• 自动解析嵌套对象结构
• 提取每个字段的类型和描述
• 支持数组类型（Array<>）
• 支持多层嵌套对象

🚀 使用方法

1. 运行生成器

pnpm api:generate

2. 查看生成结果

生成的 API 文件会保存到 src/api/ 目录，格式如下：

import { fn, fetch } from '@/api/fn';

const Api = {
  GetUserInfo: '/srv/?a=user_info',
}

/**
 * @description: 查询我的信息
 * @param {Object} params 请求参数
 * @returns {Promise<{
 *   code: number; // 状态码
 *   msg: string; // 消息
 *   data: {
 *     user: {
 *       id: integer; // 用户ID
 *       name: string; // 姓名
 *       mobile: string; // 手机号
 *     };
 *     checkin: {
 *       total_days: integer; // 累计打卡天数
 *       consecutive_days: integer; // 连续打卡天数
 *     };
 *   };
 * }>}
 */
export const getUserInfoAPI = (params) => fn(fetch.get(Api.GetUserInfo, params));

注释特点：

• ✅ 详细的返回值类型定义
• ✅ 完整的嵌套对象结构
• ✅ 每个字段的类型和描述
• ✅ 支持数组类型（Array<>）
• ✅ 参数类型和描述（如有）

3. 在项目中使用

import { getUserInfoAPI } from '@/api/user';

// 调用接口
const result = await getUserInfoAPI({ id: 123 });

📋 命名规则

常量命名（帕斯卡命名）

• 输入：getUserInfo.md
• 输出：GetUserInfo: '/srv/?a=user_info'

函数命名（驼峰命名 + API 后缀）

• 输入：getUserInfo.md
• 输出：export const getUserInfoAPI = (params) => ...

⚠️ 注意事项

1. 文件命名：建议使用驼峰命名，如 getUserInfo.md
2. Action 参数：确保每个接口的 parameters 中有 name: a 的参数
3. 模块隔离：不同模块的接口会生成到不同的文件中
4. 文件覆盖：每次运行会覆盖已生成的文件，请勿手动修改生成的文件

🔧 自定义扩展

如需修改生成逻辑，编辑 scripts/generateApiFromOpenAPI.js：

• 修改命名规则：调整 toCamelCase() 和 toPascalCase() 函数
• 修改输出格式：调整 generateApiFileContent() 函数
• 添加额外字段：在 parseOpenAPIDocument() 函数中提取更多字段

📚 完整示例

参考 docs/api-specs/user/getUserInfo.md 查看完整的 OpenAPI 文档示例。

运行生成器后，查看 src/api/user.js 查看生成的 API 文件。

🎯 最佳实践

1. 保持文档同步：修改接口后及时更新 OpenAPI 文档并重新生成
2. 版本控制：将生成的 API 文件提交到 Git
3. 代码审查：生成后检查生成的代码是否符合预期
4. 模块化管理：相关接口放在同一模块文件夹下

🐛 常见问题

Q: 生成失败怎么办？

A: 检查 YAML 格式是否正确，确保使用 yaml 代码块包裹。

Q: 如何添加新的接口？

A: 在对应的模块目录下创建新的 .md 文件，运行生成命令即可。

Q: 如何修改生成格式？

A: 编辑 scripts/generateApiFromOpenAPI.js 中的相关函数。