🚀 OpenAPI 转 API 文档生成器

从 OpenAPI 文档自动生成标准化的 JavaScript API 接口文件

✨ 特性

• 📁 自动扫描 - 递归扫描 docs/openAPI 目录结构
• 📝 YAML 解析 - 解析 OpenAPI 3.x 规范的 Markdown 文档
• 🔄 命名转换 - 自动转换为驼峰命名和帕斯卡命名
• 📦 模块化 - 按文件夹自动生成独立的 API 模块文件
• ⚡ 即插即用 - 一条命令完成所有转换
• 🎯 详细注释 - 自动生成完整的 JSDoc 注释，包含参数类型和返回值结构

📦 快速开始

1. 安装依赖

pnpm install

2. 创建 OpenAPI 文档

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

mkdir -p docs/openAPI/user

编辑 docs/openAPI/user/getUserInfo.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: user_info
        - name: f
          in: query
          example: behalo
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                properties:
                  data:
                    properties:
                      user:
                        type: object
                        properties:
                          id:
                            type: integer
                            description: 用户ID
                          name:
                            type: string
                            description: 姓名
\```

3. 生成 API 文件

pnpm api:generate

输出：

✅ 找到 1 个模块: user
✅ 生成文件: src/api/user.js

生成的文件包含详细的 JSDoc 注释：

• ✅ 参数类型和描述
• ✅ 返回值完整类型定义
• ✅ 嵌套对象结构
• ✅ 数组类型支持

4. 使用生成的 API

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

const result = await getUserInfoAPI();
console.log(result.data);

📂 项目结构

docs/openAPI/              # OpenAPI 文档源目录
├── user/                  # 模块目录
│   └── getUserInfo.md     # 接口文档
└── order/                 # 模块目录
    ├── getList.md
    └── getDetail.md

scripts/                   # 生成器脚本
├── generateApiFromOpenAPI.js  # 核心生成器
├── test-generate.js           # 测试脚本
└── QUICKSTART.md              # 快速开始指南

src/api/                    # 生成的 API 文件
├── user.js                 # 自动生成 ✨
└── order.js                # 自动生成 ✨

docs/                       # 文档
├── OPENAPI_TO_API_GUIDE.md     # 详细指南
├── API_USAGE_EXAMPLES.md       # 使用示例
└── IMPLEMENTATION_SUMMARY.md   # 实现总结

🎯 核心功能

1. 自动扫描目录

// 扫描 docs/openAPI 目录
// 识别第一级文件夹为模块名
// 识别文件夹内的 .md 文件为接口文档

2. 解析 OpenAPI 规范

# 提取以下字段：
- summary: 接口描述
- parameters: 请求参数
- a: action 值
- get/post: HTTP 方法

3. 生成标准化代码

// 输入: user/getUserInfo.md
// 输出:
const Api = {
  GetUserInfo: '/srv/?a=user_info',
}

export const getUserInfoAPI = (params) => fn(fetch.get(Api.GetUserInfo, params));

📋 命令列表

# 生成 API 文件
pnpm api:generate

# 测试生成的文件
node scripts/test-generate.js

# 启动开发服务器
pnpm dev:weapp

🔧 自定义配置

修改输出目录

编辑 scripts/generateApiFromOpenAPI.js:

const outputDir = path.resolve(__dirname, '../src/api');
// 改为其他目录

修改命名规则

编辑命名转换函数：

function toCamelCase(str) {
  // 自定义转换逻辑
}

function toPascalCase(str) {
  // 自定义转换逻辑
}

修改生成模板

编辑 generateApiFileContent() 函数。

📖 使用示例

基础用法

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

const result = await getUserInfoAPI();
if (result.code === 1) {
  console.log(result.data);
}

结合 Pinia Store

// stores/user.js
import { defineStore } from 'pinia';
import { getUserInfoAPI } from '@/api/user';

export const useUserStore = defineStore('user', {
  actions: {
    async fetchUserInfo() {
      const result = await getUserInfoAPI();
      if (result.code === 1) {
        this.userInfo = result.data;
      }
    },
  },
});

在 Vue 组件中使用

<script setup>
import { ref } from 'vue';
import { getUserInfoAPI } from '@/api/user';

const userInfo = ref(null);

const fetchUserInfo = async () => {
  const result = await getUserInfoAPI();
  if (result.code === 1) {
    userInfo.value = result.data;
  }
};
</script>

🎨 演示页面

访问演示页面查看实际效果：

# 启动开发服务器
pnpm dev:weapp

# 访问路径
pages/examples/api-demo/index

演示页面包含：

• ✅ 用户信息接口示例
• ✅ 订单列表接口示例
• ✅ 订单详情接口示例
• ✅ 完整的错误处理
• ✅ 加载状态展示

📚 文档

• 📖 详细使用指南 - 完整的功能说明
• ⚡ 快速开始指南 - 快速上手教程
• 💡 API 使用示例 - 实际使用案例
• 📊 实现总结 - 技术实现细节
• 🎯 JSDoc 生成指南 - 详细注释生成规则

✅ 测试结果

测试用例	状态	说明
单接口生成	✅ 通过	单个文件成功生成
批量接口生成	✅ 通过	多个接口批量生成
多模块生成	✅ 通过	不同模块独立生成
格式验证	✅ 通过	生成的代码格式正确

🎯 最佳实践

1. 保持文档同步 - 修改接口后及时更新 OpenAPI 文档
2. 统一命名规范 - 使用驼峰命名文件名
3. 模块化组织 - 相关接口放在同一模块下
4. 版本控制 - 将生成的 API 文件提交到 Git
5. 代码审查 - 生成后检查代码是否符合预期

🔍 常见问题

Q: 如何添加新接口？

A: 在对应模块目录下创建新的 .md 文件，运行 pnpm api:generate

Q: 如何添加新模块？

A: 创建新的模块文件夹，添加接口文档，运行生成命令

Q: 生成的文件可以手动修改吗？

A: 不建议，每次运行生成命令会覆盖已生成的文件

Q: 如何修改生成格式？

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

🚧 后续规划

• TypeScript 类型定义生成
• Mock 数据自动生成
• Watch 模式监听文件变化
• 增量生成（只生成修改过的文件）
• 可视化配置界面

📞 获取帮助

遇到问题？

1. 查看 详细使用指南
2. 查看 API 使用示例
3. 运行 node scripts/test-generate.js 诊断问题

📄 许可证

MIT

---

现在就开始使用，简化你的 API 开发流程！ 🎉