Update

/apispec:update - 更新 API 文档

解析当前项目的路由和 handler，生成/更新 API 文档到规范仓库。

使用方式

/apispec:update              # 更新所有 API
/apispec:update auth         # 只更新 auth 模块

前置条件

• 项目已执行 /apispec:init，存在 .api-spec.yaml 配置文件
• API specs 仓库已 clone 到本地

执行步骤

Step 1: 读取配置

if [ ! -f ".api-spec.yaml" ]; then
    echo "错误：未找到 .api-spec.yaml，请先执行 /apispec:init"
    exit 1
fi

Step 2: 解析路由文件

根据项目类型解析路由：

Go 项目：

• 解析 routes.go 中的 mux.HandleFunc 和 mux.Handle 调用
• 提取 HTTP 方法、路径、handler 函数名
• 读取对应的 handler 文件，提取请求/响应结构体

Node.js 项目：

• 解析 router.get/post/put/delete 调用
• 提取路由和 handler

Python 项目：

• 解析 urlpatterns 或 Flask/FastAPI 路由装饰器

Step 3: 生成 API 文档

为每个 API 生成 YAML 文件：

{spec_repo}/{project_name}/
├── meta.yaml           # 项目索引
├── auth/
│   ├── sms-send.yaml
│   └── sms-login.yaml
├── user/
│   └── get-profile.yaml
└── ...

meta.yaml 格式：

project: {project_name}
description: {description}
base_url: {base_url}
updated_at: {timestamp}
apis:
  - path: auth/sms-send
    method: POST
    endpoint: /api/v1/auth/sms/send
    auth: false
    summary: 发送短信验证码

单个 API 文件格式：

endpoint: /api/v1/auth/sms/login
method: POST
summary: 短信验证码登录
auth: false
description: 使用手机号和短信验证码登录

request:
  content_type: application/json
  fields:
    - name: phone
      type: string
      required: true
      description: 手机号

response:
  success:
    status: 200
    fields:
      - name: token
        type: string
        description: JWT token
  errors:
    - status: 400
      error: invalid_code
      description: 验证码错误

Step 4: 更新全局索引

更新 {spec_repo}/meta.yaml：

projects:
  {project_name}:
    description: {description}
    base_url: {base_url}
    api_count: {count}
    updated_at: {timestamp}

Step 5: 提交并推送

cd {spec_repo}
git add -A
git commit -m "docs: update {project_name} API specs"
git push origin main

输出

• 更新 {spec_repo}/{project_name}/ 目录下的所有 API 文档
• 自动 commit 并 push 到远程仓库
• 显示更新摘要（新增/修改/删除的 API 数量）