skill.md 11.6 KB

Raw Blame History Permalink



API Generator Skill

自动从 OpenAPI 文档生成前端 API 调用代码的完整解决方案。


功能特性


核心功能


自动生成 API 代码 - 从 OpenAPI YAML 文档生成标准的 API 调用函数

变更检测 - 自动对比 API 变更，识别破坏性变更

增量更新 - 智能备份和基线管理，只检测实际变更

JSDoc 注释 - 自动生成完整的类型注释和参数说明


生成内容


API 常量 - 帕斯卡命名的端点常量（如 GET_USER_INFO）

API 函数 - 驼峰命名的调用函数（如 getUserInfoAPI）

完整 JSDoc - 参数类型、返回值结构、嵌套对象说明


快速开始


第一次使用


创建 OpenAPI 文档


# 在 docs/api-specs/ 创建模块目录
mkdir -p docs/api-specs/user

# 创建接口文档（使用下方模板）
cp .claude/custom_skills/api-generator/templates/api-specs-template.md docs/api-specs/user/getUserInfo.md


编辑 OpenAPI 文档


按照 OpenAPI 3.0.1 规范编辑 YAML 代码块：

# 获取用户信息

## OpenAPI Specification

```yaml
openapi: 3.0.1
info:
  title: ''
  version: 1.0.0
paths:
  /srv/:
    get:
      summary: 获取用户信息
      parameters:
        - name: a
          in: query
          example: user_info
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                  data:
                    type: object


生成 API 代码


# 安装依赖（首次）
pnpm add -D js-yaml

# 生成 API 代码
pnpm api:generate


使用生成的 API


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

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


依赖安装


必需依赖

pnpm add -D js-yaml


package.json 配置

{
  "scripts": {
    "api:generate": "node .claude/custom_skills/api-generator/scripts/generateApiFromOpenAPI.js",
    "api:diff": "node .claude/custom_skills/api-generator/scripts/apiDiff.js"
  }
}


目录结构

docs/api-specs/
├── user/                    # 用户模块
│   ├── getUserInfo.md       # 获取用户信息
│   └── editUserInfo.md      # 编辑用户信息
├── course/                  # 课程模块
│   ├── getList.md           # 获取课程列表
│   └── getDetail.md         # 获取课程详情
└── order/                   # 订单模块
    └── getList.md           # 获取订单列表


重要规则：


第一级目录 = 模块名（生成 模块名.js 文件）
第二级文件 = 接口名（生成 接口名API 函数）


OpenAPI 文档规范


基本结构

每个 .md 文件必须包含一个 YAML 代码块：

# 接口标题

## OpenAPI Specification

```yaml
openapi: 3.0.1
info:
  title: ''
  version: 1.0.0
paths:
  /srv/:
    get:              # 或 post
      summary: 接口简介
      parameters:     # GET 请求参数
        - name: a
          in: query
          example: action_name
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                  data:
                    type: any


GET 请求示例

paths:
  /srv/:
    get:
      summary: 获取课程列表
      parameters:
        - name: a
          in: query
          example: course_list
        - name: page
          in: query
          description: 页码
          required: true
          schema:
            type: integer
        - name: limit
          in: query
          description: 每页数量
          schema:
            type: integer


POST 请求示例

paths:
  /srv/:
    post:
      summary: 创建订单
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
                - course_id
              properties:
                course_id:
                  type: integer
                  description: 课程ID
                quantity:
                  type: integer
                  description: 数量


响应结构示例

responses:
  '200':
    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
                    name:
                      type: string
                items:
                  type: array
                  items:
                    type: object
                    properties:
                      id:
                        type: integer
                      title:
                        type: string


生成的代码示例


输入：docs/api-specs/user/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; // 状态码
 *   msg: string; // 消息
 *   data: any;
 * }>}
 */
export const getUserInfoAPI = (params) => fn(fetch.get(Api.GetUserInfo, params));


变更检测


自动变更检测

每次运行 pnpm api:generate 时会自动：


备份当前文档到 /.tmp/openAPI-backup

与上次版本对比（保存在 /.tmp/openAPI-temp）
生成变更报告


变更报告示例

🔍 开始检测 API 变更...

=== API 变更检测报告 ===

📦 对比范围: 5 个旧接口 → 6 个新接口
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

✅ 新增接口 (1):
  + getUserProfile

⚠️  修改接口 (2):
  ↪ editUserInfo
    ✗ [破坏性] 删除必填参数: sms_code
    ✓ [非破坏性] 新增可选参数: avatar

  ↪ getUserInfo
    ✓ [非破坏性] 新增可选参数: include_profile

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
总计: 1 新增, 2 修改, 0 删除
⚠️  检测到 1 个破坏性变更，请仔细检查业务逻辑！


手动对比

# 对比两个目录
pnpm api:diff docs/api-specs/user/ docs/api-specs/user-new/

# 对比两个文件
pnpm api:diff docs/api-specs/user/getInfo.md docs/api-specs/user/getInfo-v2.md

# 输出 JSON 格式
API_DIFF_FORMAT=json pnpm api:diff ...


高级配置


环境变量

# 严格模式：任何变更都返回失败码
API_DIFF_STRICT=true pnpm api:generate

# JSON 格式输出
API_DIFF_FORMAT=json pnpm api:diff ...


自定义输出路径

编辑 scripts/generateApiFromOpenAPI.js 底部：

// 修改输入/输出路径
const openAPIDir = path.resolve(__dirname, '../../docs/api-specs');
const outputDir = path.resolve(__dirname, '../../src/api');


跨项目使用


方法 1：复制整个 skill

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

# 复制 npm 脚本
# 在其他项目的 package.json 中添加 scripts

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


方法 2：使用安装脚本

# 在目标项目中运行
bash .claude/custom_skills/api-generator/setup/install.sh


工作流程


开发新接口


创建文档 - 在 docs/api-specs/模块名/接口名.md


编写规范 - 按照 OpenAPI 3.0.1 规范编写 YAML

生成代码 - 运行 pnpm api:generate


检查变更 - 查看变更报告，确认没有破坏性变更

使用代码 - 在组件中导入并使用生成的 API 函数


修改接口


更新文档 - 修改对应的 .md 文件

生成代码 - 运行 pnpm api:generate


检查影响 - 查看变更报告，评估影响范围

更新业务 - 根据变更类型更新业务代码


破坏性变更：必须修改业务代码
非破坏性变更：可选修改


删除接口


删除文档 - 删除对应的 .md 文件

生成代码 - 运行 pnpm api:generate


检查引用 - 全局搜索被删除的 API 函数，移除引用


常见问题


Q: 生成代码后报错找不到模块？

A: 检查以下几点：


确认 src/api/fn.js 存在且导出 fn 和 fetch

确认路径别名 @/ 正确配置
确认生成的文件在 src/api/ 目录下


Q: 如何处理需要认证的接口？

A: 生成的代码会自动使用 src/utils/axios.js 中的拦截器，自动添加认证头。无需特殊处理。


Q: 如何处理不同的请求方法？

A: 脚本会自动识别：


get → fetch.get()


post → fetch.post()


application/x-www-form-urlencoded → fetch.stringifyPost()


Q: 生成的代码格式不统一？

A: 运行 pnpm lint 自动格式化生成的代码。


Q: 如何复用已有的 API 定义？

A: 可以在 YAML 中使用 $ref 引用，但当前版本暂不支持，建议直接展开定义。


最佳实践


1. 文档命名规范


模块目录: 小写，多个单词用下划线（user_profile）

接口文件: 小写，动词开头（getUserInfo.md）


2. 接口分组


按业务模块分组（user, course, order）
避免单个模块过大（建议 < 20 个接口）
相关接口放在同一模块


3. 版本管理


将 docs/api-specs/ 纳入版本控制
生成的 src/api/*.js 也纳入版本控制
保留变更历史，方便回滚


4. 团队协作


前后端共同维护 OpenAPI 文档
接口变更前先更新文档
使用变更报告评估影响
破坏性变更必须通知团队


5. 文档注释


summary: 简短描述（1行）

description: 详细说明（可选）

参数: 每个参数都应有 description

响应: 嵌套对象也应有说明


故障排除


问题：YAML 解析失败

错误信息: 解析 OpenAPI 文档失败: YAMLException

解决方案:


检查 YAML 缩进（必须使用空格，不能用 Tab）
检查 YAML 语法（使用在线验证器）
确保所有字符串正确引号包裹


问题：生成的函数名不符合预期

原因: 文件名包含特殊字符

解决方案:


使用小写字母和数字
多个单词用下划线分隔
避免使用中划线（会转换为驼峰）


问题：变更检测不准确

原因: 首次运行或备份文件损坏

解决方案:

# 清理备份
rm -rf .tmp/openAPI-*

# 重新建立基线
pnpm api:generate


相关资源


OpenAPI 3.0 规范
YAML 语法指南
API 设计最佳实践


更新日志


v1.0.0 (2026-01-29)


✨ 初始版本
✅ 支持 GET/POST 请求
✅ 自动生成 JSDoc 注释
✅ API 变更检测
✅ 增量更新机制
✅ 跨项目支持