API 规范管理工具

跨项目 API 文档的初始化、更新、查询与搜索。包含四个功能模块：init（初始化）、lookup（查询）、search（搜索）、update（更新）。

1. Init - 初始化项目 API 文档配置

初始化当前后端项目的 API 文档配置，生成 .api-spec.yaml 文件。

使用方式

apispec init

执行步骤

Step 1: 检测项目类型

检查项目结构，识别后端框架：

# Go 项目
if [ -f "go.mod" ]; then
    PROJECT_TYPE="go"
    ROUTES_FILE=$(find . -name "routes.go" -o -name "router.go" | head -1)
fi

# Node.js 项目
if [ -f "package.json" ]; then
    PROJECT_TYPE="node"
    ROUTES_FILE=$(find . -name "routes.ts" -o -name "routes.js" -o -name "router.ts" | head -1)
fi

# Python 项目
if [ -f "requirements.txt" ] || [ -f "pyproject.toml" ]; then
    PROJECT_TYPE="python"
    ROUTES_FILE=$(find . -name "urls.py" -o -name "routes.py" | head -1)
fi

Step 2: 收集项目信息

使用 AskUserQuestion 工具询问以下信息（如果无法自动检测）：

1. 项目名称 - 用于在 API 规范仓库中创建目录
2. Base URL - 生产环境的 API 地址
3. 路由文件位置 - 如果自动检测不准确

Step 3: 生成配置文件

在项目根目录创建 .api-spec.yaml：

# API 规范配置
project_name: {project_name}
description: {description}
base_url: {base_url}

# API 规范仓库位置
spec_repo: ~/.apispec/registry

# 路由文件位置（用于解析 API）
routes_file: {routes_file}

# 项目类型
project_type: {go|node|python}

Step 4: 确认配置

显示生成的配置文件内容，询问用户确认。

输出

• 在项目根目录创建 .api-spec.yaml 文件
• 将 .api-spec.yaml 添加到 .gitignore（可选）

注意事项

• 如果 .api-spec.yaml 已存在，询问是否覆盖
• spec_repo 默认为 ~/.apispec/registry
• 需确保 API specs 仓库已 clone 到该目录

2. Lookup - 查询 API 文档

查询项目的 API 文档，支持列出所有项目、查看项目 API 列表、查看具体 API 详情。

使用方式

apispec lookup                              # 列出所有项目
apispec lookup {project}                    # 显示项目的所有 API
apispec lookup {project} {module}           # 显示模块下的 API
apispec lookup {project} {module}/{api}     # 显示具体 API 详情

示例

apispec lookup                              # 列出所有项目
apispec lookup myapp                        # 显示 myapp 的所有 API
apispec lookup myapp auth                   # 显示 auth 模块的 API
apispec lookup myapp auth/sms-login         # 显示 sms-login 的详细文档

执行步骤

Step 1: 定位规范仓库

默认路径：~/.apispec/registry

如果目录不存在，提示用户 clone 仓库：

mkdir -p ~/.apispec
git clone \x3Cyour-api-specs-repo> ~/.apispec/registry

Step 2: 拉取最新

cd {spec_repo}
git pull origin main --quiet

Step 3: 根据参数查询

无参数 - 列出所有项目：

读取 meta.yaml，格式化输出：

API Specifications Registry

Projects:
  myapp          用户中心服务 - 认证、会员、支付    20 APIs
  another-app    其他项目描述                      12 APIs

一个参数 - 显示项目 API 列表：

读取 {project}/meta.yaml，格式化输出：

myapp - 用户中心服务
Base URL: https://api.example.com
Updated: 2026-01-22

APIs (20):
  METHOD  ENDPOINT                        AUTH  SUMMARY
  POST    /api/v1/auth/sms/send           -     发送短信验证码
  POST    /api/v1/auth/sms/login          -     短信验证码登录
  GET     /api/v1/user/profile            *     获取用户信息
  PUT     /api/v1/user/profile            *     更新用户信息

* = 需要认证

两个参数（模块）- 显示模块 API：

筛选显示指定模块的 API。

完整路径 - 显示 API 详情：

读取 {project}/{module}/{api}.yaml，格式化输出完整的请求/响应信息。

输出格式

• 简洁的文本格式，便于快速理解
• 字段对齐，易于阅读
• 只显示必要信息，减少 token 消耗

注意事项

• 每次查询前自动 git pull 获取最新文档
• 如果项目或 API 不存在，给出友好提示并建议使用 apispec search 模糊查找

3. Search - 模糊搜索 API 文档

跨项目模糊搜索 API 文档，支持按关键词、路径、方法、字段名等维度匹配。

使用方式

apispec search {keyword}                    # 全局模糊搜索
apispec search --project {name} {keyword}   # 在指定项目中搜索
apispec search --method POST {keyword}      # 按 HTTP 方法过滤
apispec search --field {fieldname}          # 按请求/响应字段名搜索

示例

apispec search login                        # 搜索包含 "login" 的 API
apispec search 验证码                        # 中文关键词搜索
apispec search --method POST user           # 搜索 POST 方法中包含 "user" 的 API
apispec search --field token                # 搜索请求或响应中包含 token 字段的 API
apispec search --project myapp auth         # 在 myapp 项目中搜索 "auth"

执行步骤

Step 1: 定位规范仓库

默认路径：~/.apispec/registry

如果目录不存在，提示用户先执行 apispec init 并 clone 仓库。

Step 2: 拉取最新

cd {spec_repo}
git pull origin main --quiet

Step 3: 搜索匹配

搜索范围（按优先级）：

1. endpoint 路径 - URL 路径中包含关键词
2. summary/description - API 描述中包含关键词
3. 请求/响应字段名 - field name 匹配
4. 模块/文件名 - 目录或文件名匹配

搜索逻辑：

# 遍历所有项目的 meta.yaml 和 API 文件
for project_dir in {spec_repo}/*/; do
    # 读取 meta.yaml 中的 API 列表快速匹配
    # 如果 meta 匹配不够，深入读取具体 API 文件
done

支持多关键词（AND 逻辑）：

apispec search POST login    # 匹配同时包含 POST 和 login 的 API

Step 4: 格式化输出

匹配结果格式：

搜索 "login" - 找到 3 个匹配：

  METHOD  PROJECT      ENDPOINT                     SUMMARY
  POST    myapp        /api/v1/auth/sms/login       短信验证码登录
  POST    myapp        /api/v1/auth/wechat/login    微信登录
  POST    another-app  /api/v1/login                密码登录

提示：使用 apispec lookup myapp auth/sms-login 查看详情

无匹配时：

搜索 "xyz" - 未找到匹配的 API

建议：
  - 尝试更短的关键词
  - 使用 apispec lookup 浏览项目列表
  - 检查拼写是否正确

字段搜索结果：

搜索字段 "token" - 找到 5 个匹配：

  METHOD  PROJECT  ENDPOINT                   字段位置     字段类型
  POST    myapp    /api/v1/auth/sms/login     response    string
  POST    myapp    /api/v1/auth/wechat/login  response    string
  POST    myapp    /api/v1/auth/refresh       request     string
  GET     myapp    /api/v1/user/profile       request.header  string
  DELETE  myapp    /api/v1/auth/logout        request.header  string

提示：使用 apispec lookup myapp auth/sms-login 查看完整 API 定义

注意事项

• 搜索不区分大小写
• 支持中英文关键词
• 结果按相关度排序（endpoint 匹配 > summary 匹配 > field 匹配）
• 最多显示 20 条结果，超出时提示缩小搜索范围
• 每次搜索前自动 git pull 获取最新文档

4. 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 数量）