OpenAPI 文档目录

本目录用于存放 OpenAPI 规范的接口文档，这些文档将自动转换为前端 API 调用代码。

快速开始

1. 创建新接口文档

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

# 复制模板
cp .claude/custom_skills/api-generator/templates/api-specs-template.md \
   docs/api-specs/yourModule/yourApiName.md

2. 编辑 OpenAPI 文档

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

3. 生成 API 代码

yarn api:generate

生成的代码将保存在 src/api/ 目录。

4. 使用生成的 API

import { yourApiNameAPI } from '@/api/yourModule'

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

目录结构

docs/api-specs/
├── example/              # 示例模块
│   └── getExample.md     # 示例接口
├── user/                 # 用户模块（你的模块）
│   ├── getUserInfo.md    # 获取用户信息
│   └── editUserInfo.md   # 编辑用户信息
├── course/               # 课程模块（你的模块）
│   ├── getList.md        # 获取课程列表
│   └── getDetail.md      # 获取课程详情
└── order/                # 订单模块（你的模块）
    └── getList.md        # 获取订单列表

重要规则：

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

命令速查

# 生成 API 代码
yarn api:generate

# 对比 API 变更
yarn api:diff docs/api-specs/user/ docs/api-specs/user-new/

# 查看完整文档
cat .claude/custom_skills/api-generator/skill.md

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 请求示例

```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

响应结构示例

responses:
  '200':
    content:
      application/json:
        schema:
          type: object
          properties:
            code:
              type: integer
              description: 0=失败，1=成功
            data:
              type: object
              properties:
                user:
                  type: object
                  properties:
                    id:
                      type: integer

生成的代码示例

输入：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))

变更检测

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

1. 备份当前文档到 /.tmp/openAPI-backup
2. 与上次版本对比（保存在 /.tmp/openAPI-temp）
3. 生成变更报告

变更报告示例

🔍 开始检测 API 变更...

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

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

✅ 新增接口 (1):
  + getUserProfile

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

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

注意事项

• 所有 .md 文件必须包含 YAML 代码块
• 遵循 OpenAPI 3.0.1 规范编写 YAML
• 文件名使用小写字母和数字，多个单词用下划线分隔
• 参数 a 和 f 会被自动过滤，不会在 JSDoc 中显示
• 生成的代码会自动使用项目的 src/api/fn.js 中的 fn 和 fetch

参考文档

详细使用说明请参考：API Generator Skill 文档

示例

查看 example/getExample.md 了解完整的文档编写示例。