API_GENERATOR_GUIDE.md
7.03 KB
API Generator - 自动生成 API 接口代码
完整的 API 文档自动生成解决方案，从 OpenAPI 规范到前端 API 调用代码。
🚀 快速开始
安装依赖
yarn add -D js-yaml
创建第一个接口文档
# 1. 创建模块目录
mkdir -p docs/openAPI/user
# 2. 复制模板
cp .claude/custom_skills/api-generator/templates/openAPI-template.md \
docs/openAPI/user/getUserInfo.md
# 3. 编辑文档（按照模板填写）
# 4. 生成代码
yarn api:generate
生成的代码：src/api/user.js
import { getUserInfoAPI } from '@/api/user'
const { code, data } = await getUserInfoAPI({ id: 123 })
if (code === 1) {
console.log(data)
}
📚 核心功能
1. 自动生成 API 代码
从 OpenAPI YAML 文档生成标准的 API 调用函数：
-
API 常量 - 帕斯卡命名（
GetUserInfo） -
API 函数 - 驼峰命名 + API 后缀（
getUserInfoAPI） - 完整 JSDoc - 参数类型、返回值结构、嵌套对象说明
2. 智能变更检测
自动对比 API 变更，识别破坏性变更：
- ✅ 新增接口
- ⚠️ 参数变更（破坏性/非破坏性）
- ❌ 删除接口
3. 增量更新机制
- 首次运行建立基线
- 后续运行自动对比
- 生成详细变更报告
📁 目录结构
docs/openAPI/ # OpenAPI 文档目录
├── example/ # 示例模块
│ └── getExample.md # 示例接口
├── user/ # 用户模块
│ ├── getUserInfo.md # 获取用户信息
│ └── editUserInfo.md # 编辑用户信息
└── README.md # 本文档
.claude/custom_skills/api-generator/ # Skill 目录
├── skill.md # Skill 主文档
├── scripts/ # 生成脚本
│ ├── generateApiFromOpenAPI.cjs
│ └── apiDiff.cjs
├── templates/ # 文档模板
│ └── openAPI-template.md
└── setup/ # 安装脚本
└── install.sh
📝 OpenAPI 文档规范
基本结构
每个 .md 文件必须包含 YAML 代码块：
# 接口名称
## OpenAPI Specification
```yaml
openapi: 3.0.1
info:
title: ''
version: 1.0.0
paths:
/srv/:
get:
summary: 接口简介
parameters:
- name: a
in: query
example: action_name
responses:
'200':
content:
application/json:
schema:
type: object
properties:
code:
type: integer
data:
type: any
### GET 请求示例
```yaml
paths:
/srv/:
get:
summary: 获取课程列表
parameters:
- name: a
in: query
example: course_list
- name: page
in: query
description: 页码
required: true
schema:
type: integer
POST 请求示例
paths:
/srv/:
post:
summary: 创建订单
requestBody:
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
course_id:
type: integer
🎯 命令使用
生成 API 代码
# 使用 yarn
yarn api:generate
# 或直接运行
node .claude/custom_skills/api-generator/scripts/generateApiFromOpenAPI.cjs
对比 API 变更
# 对比两个目录
yarn api:diff docs/openAPI/user/ docs/openAPI/user-new/
# 对比两个文件
yarn api:diff docs/openAPI/user/getInfo.md docs/openAPI/user/getInfo-v2.md
# 输出 JSON 格式
API_DIFF_FORMAT=json yarn api:diff ...
📊 生成示例
输入文档：getUserInfo.md
paths:
/srv/:
get:
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))
🔄 变更检测示例
yarn api:generate
输出报告：
🔍 开始检测 API 变更...
=== API 变更检测报告 ===
📦 对比范围: 5 个旧接口 → 6 个新接口
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✅ 新增接口 (1):
+ getUserProfile
⚠️ 修改接口 (1):
↪ editUserInfo
✗ [破坏性] 删除必填参数: sms_code
✓ [非破坏性] 新增可选参数: avatar
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
总计: 1 新增, 1 修改, 0 删除
⚠️ 检测到 1 个破坏性变更，请仔细检查业务逻辑！
💡 最佳实践
1. 文档命名
-
模块目录：小写，下划线分隔（
user_profile） -
接口文件：小写，动词开头（
getUserInfo.md）
2. 接口分组
- 按业务模块分组（
user,course,order） - 避免单个模块过大（< 20 个接口）
- 相关接口放在同一模块
3. 版本管理
-
docs/openAPI/纳入版本控制 -
src/api/*.js也纳入版本控制 - 保留变更历史，方便回滚
4. 团队协作
- 前后端共同维护 OpenAPI 文档
- 接口变更前先更新文档
- 使用变更报告评估影响
- 破坏性变更必须通知团队
🛠️ 跨项目使用
方法 1：复制 Skill
# 复制到其他项目
cp -r .claude/custom_skills/api-generator /other/project/.claude/custom_skills/
# 安装依赖
cd /other/project
yarn add -D js-yaml
# 添加脚本（手动编辑 package.json）
方法 2：使用安装脚本
bash .claude/custom_skills/api-generator/setup/install.sh
❓ 常见问题
Q: 生成代码后报错找不到模块？
A: 检查以下几点：
-
src/api/fn.js存在且导出fn和fetch - 路径别名
@/正确配置 - 生成的文件在
src/api/目录下
Q: 如何处理需要认证的接口？
A: 生成的代码会自动使用 src/utils/axios.js 中的拦截器，自动添加认证头。
Q: 生成的函数名不符合预期？
A: 文件名使用小写字母和数字，多个单词用下划线分隔，避免特殊字符。
Q: 变更检测不准确？
A: 清理备份重新建立基线：
rm -rf .tmp/openAPI-*
yarn api:generate
📖 完整文档
详细使用说明请参考：API Generator Skill 文档