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 <your-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，格式化输出完整的请求/响应信息。