API Generator 功能移植完成

📋 任务概述

将 manulife-weapp 项目的 OpenAPI 文档自动生成功能移植到 mlaj 项目，并封装成完整的 skill。

✅ 完成内容

1. 核心功能移植

• ✅ API 生成脚本 - generateApiFromOpenAPI.cjs

  • 扫描 docs/openAPI/ 目录
  • 解析 OpenAPI 3.0.1 YAML 文档
  • 生成标准的 API 调用代码（常量 + 函数 + JSDoc）
  • 自动备份和变更检测

• ✅ API 对比工具 - apiDiff.cjs

  • 对比两个版本的 OpenAPI 文档
  • 检测新增、修改、删除的接口
  • 识别破坏性变更和非破坏性变更
  • 生成详细的变更报告

2. Skill 封装

创建了完整的 skill 目录结构：

.claude/custom_skills/api-generator/
├── skill.md                           # Skill 主文档（完整使用指南）
├── scripts/
│   ├── generateApiFromOpenAPI.cjs    # API 生成脚本
│   └── apiDiff.cjs                    # API 对比脚本
├── templates/
│   └── openAPI-template.md           # OpenAPI 文档模板
└── setup/
    └── install.sh                     # 跨项目安装脚本

3. 项目集成

• ✅ 依赖安装：js-yaml@4.1.1
• ✅ npm scripts：
  • api:generate - 生成 API 代码
  • api:diff - 对比 API 变更
• ✅ 示例文档：docs/openAPI/example/getExample.md
• ✅ 使用指南：docs/openAPI/README.md
• ✅ 完整文档：docs/tools/API_GENERATOR_GUIDE.md

4. 文档更新

• ✅ 创建 docs/tools/API_GENERATOR_GUIDE.md - 完整使用指南
• ✅ 更新 docs/tools/SKILLS_GUIDE.md - 添加 API Generator 入口
• ✅ 创建 docs/openAPI/README.md - OpenAPI 目录说明
• ✅ 创建示例文档和模板

🎯 功能特性

自动生成能力

• API 常量：帕斯卡命名（如 GetUserInfo）
• API 函数：驼峰命名 + API 后缀（如 getUserInfoAPI）
• 完整 JSDoc：
  • 参数类型和说明
  • 返回值结构（嵌套对象）
  • 数组类型支持

智能变更检测

• 🆕 新增接口检测
• ⚠️ 参数变更检测（破坏性/非破坏性）
• ❌ 删除接口检测
• 📊 详细变更报告

增量更新机制

• 首次运行建立基线
• 后续运行自动对比
• 识别实际变更，避免误报

📖 使用示例

创建新接口

1. 创建文档

   mkdir -p docs/openAPI/user
   cp .claude/custom_skills/api-generator/templates/openAPI-template.md \
      docs/openAPI/user/getUserInfo.md

1. 编辑 OpenAPI 文档

   paths:
     /srv/:
       get:
         summary: 获取用户信息
         parameters:
           - name: a
             example: user_info
           - name: id
             description: 用户ID
             required: true

1. 生成代码

   yarn api:generate

1. 使用生成的 API

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

   const { code, data } = await getUserInfoAPI({ id: 123 })
   if (code === 1) {
     console.log(data)
   }

生成的代码示例

输入文档：getUserInfo.md

summary: 获取用户信息
parameters:
  - name: a
    example: user_info
  - name: id
    description: 用户ID
    required: true

输出代码：src/api/user.js

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

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

/**
 * @description: 获取用户信息
 * @param {Object} params 请求参数
 * @param {integer} params.id 用户ID
 * @returns {Promise<{code:number,data:any,msg:string}>}
 */
export const getUserInfoAPI = params => fn(fetch.get(Api.GetUserInfo, params))

🚀 跨项目使用

方法 1：复制 Skill

# 复制到其他项目
cp -r .claude/custom_skills/api-generator /other/project/.claude/custom_skills/

# 安装依赖
cd /other/project
yarn add -D js-yaml

# 添加 scripts（手动编辑 package.json）

方法 2：使用安装脚本

bash .claude/custom_skills/api-generator/setup/install.sh

📚 文档资源

• 完整使用指南：docs/tools/API_GENERATOR_GUIDE.md
• Skill 主文档：.claude/custom_skills/api-generator/skill.md
• OpenAPI 目录说明：docs/openAPI/README.md
• OpenAPI 文档模板：.claude/custom_skills/api-generator/templates/openAPI-template.md

✨ 优势与改进

相比原版本的改进

1. 更好的封装 - 完整的 skill 结构，包含所有必要文件
2. 更清晰的文档 - 完整的使用指南和示例
3. 更方便的安装 - 一键安装脚本
4. 更灵活的使用 - 支持跨项目复用

核心优势

• ✅ 自动化程度高 - 一条命令完成所有转换
• ✅ 标准化输出 - 统一的代码格式和注释风格
• ✅ 变更追踪 - 自动检测 API 变更
• ✅ 模块化组织 - 按模块独立生成
• ✅ 类型安全 - 详细的 JSDoc 类型定义
• ✅ 即时反馈 - 生成结果立即可用

🎉 总结

成功移植并优化了 OpenAPI 文档生成功能，封装成完整的 skill，提供：

1. 完整的文档体系 - 从快速开始到高级配置
2. 便捷的使用方式 - 简单的命令行接口
3. 强大的生成能力 - 支持完整的 OpenAPI 规范
4. 智能的变更检测 - 识别破坏性变更
5. 跨项目复用 - 一键安装到其他项目

这个功能将大大提高 API 开发效率，减少手动编写代码的时间，并确保 API 定义的一致性。