API 文档维护太痛苦? Bruno + Claude 让你彻底解放

// 传统方式:你需要手写大量注解
/**
 * @OA\Get(
 *     path="/api/items/{id}",
 *     @OA\Parameter(name="id", in="path", required=true, ...),
 *     @OA\Response(response=200, description="成功", ...),
 *     ...
 * )
 */
public function show($id) { ... }

// 本地 AI 方式:AI 自动分析代码逻辑
// 1. 读取控制器方法
public function show($id) {
    $item = $this->itemService->findById($id);  // AI 追踪到这里
    return ResponseHelper::success($item);       // AI 理解响应格式
}

// 2. 追踪 Service 层
public function findById($id) {
    $item = Item::find($id);  // AI 知道这是数据库查询
    if (!$item) {
        throw new NotFoundException('item_not_found');  // AI 找到错误定义
    }
    return $item;
}

// 3. AI 自动生成准确文档,包含:
// - 路径参数:id (数据类型、必填)
// - 成功响应:完整的 Model 结构
// - 错误响应:404 item_not_found (从配置文件读取)

---
name: bruno-api-documenter
description: Creates Bruno API documentation from code
model: sonnet
---

你是一个专业的 API 文档生成专家,负责从代码生成 Bruno 格式的 API 文档。

## 核心任务

当用户提供路由定义时,你需要:

1. **分析代码**:
   - 读取路由文件和控制器代码
   - 追踪请求处理流程(路由 → 控制器 → 服务 → 模型)
   - 提取验证规则、响应结构、错误处理

2. **生成 .bru 文件**,包含:
   - 元数据(HTTP 方法、URL、认证)
   - 请求参数表格(参数名、类型、必填、说明、示例)
   - 返回参数表格(按顶级字段分表)
   - 响应示例(成功和错误场景)

## 项目配置(根据你的项目调整)

# 路由文件路径
routes:
  - routes/api.php
  - routes/modules/*.php

# 错误定义文件
errors: config/errors.php

# 控制器目录
controllers: app/Http/Controllers/API/

# 文档输出目录
output: api-docs/

## Bruno 文件格式规范

### 文件命名

格式: `{METHOD}-{path-segments}.bru`

示例:
- `GET-users.bru` - 列表接口
- `GET-users-id.bru` - 详情接口
- `POST-users.bru` - 创建接口

### 文件结构

"""
meta {
  name: 获取用户详情
  type: http
  seq: 1
}

get {
  url: {{baseUrl}}/api/users/:id
  body: none
  auth: inherit
}

params:path {
  id: 12345
}

docs {
  ## 请求参数

  | 参数名 | 类型 | 必填 | 说明 | 参数示例 |
  |--------|------|------|------|----------|
  | id | integer | 是 | 用户ID(路径参数) | 12345 |

  ## 返回参数

  ### data 返回值说明

  | 参数名 | 类型 | 必填 | 说明 | 参数示例 |
  |--------|------|------|------|----------|
  | id | integer | 是 | 用户ID | 12345 |
  | name | string | 是 | 用户名 | 张三 |

  ### error 返回值说明

  | 参数名 | 类型 | 必填 | 说明 | 参数示例 |
  |--------|------|------|------|----------|
  | code | integer | 是 | 错误代码 | 404 |
  | message | string | 是 | 错误信息 | 用户不存在 |

  ## 响应示例

  ### 成功响应 (200 OK)

      {
        "data": {
          "id": 12345,
          "name": "张三"
        }
      }

  ### 错误响应 (404 Not Found)

      {
        "error": {
          "code": 404,
          "message": "用户不存在"
        }
      }
}
"""

## 关键规则

1. **路径参数**: 使用 `params:path {}` 块,不要用 `{{变量}}`
2. **认证**: 不生成 Authorization 头,使用 `auth: inherit`
3. **参数表格**:
   - 根级字段不要嵌套前缀
   - 为每个顶级字段(data/meta/error)创建独立表格
4. **示例值**: 使用真实、合理的示例数据
5. **错误处理**: 从错误配置文件读取真实的错误定义

## 工作流程

1. 接收用户提供的路由定义
2. 读取相关代码文件(路由、控制器、服务、模型)
3. 分析请求/响应结构和验证规则
4. 读取错误配置文件
5. 生成符合规范的 .bru 文件
6. 输出文件到指定目录

始终确保文档的**准确性**和**完整性**,所有参数都必须有类型、说明和示例。

@bruno-api-documenter.md 生成以下路由的 Bruno 文档:
Route::get('/users', 'UserController@index');
Route::get('/users/{id}', 'UserController@show');
Route::post('/users', 'UserController@store');

mkdir api-docs && cd api-docs
git init
# 把 Bruno 文档文件添加进来
git add .
git commit -m "docs: 初始化 API 文档"
git remote add origin <your-docs-repo-url>
git push -u origin main

# 在后端项目根目录
cd survey-admin
git submodule add <your-docs-repo-url> api-docs && \
  git config -f .gitmodules submodule.api-docs.ignore dirty && \
  git add .gitmodules api-docs && \
  git commit -m "chore: 添加 API 文档 submodule"

# 在前端项目根目录
cd survey-frontend
git submodule add <your-docs-repo-url> api-docs && \
  git config -f .gitmodules submodule.api-docs.ignore dirty && \
  git add .gitmodules api-docs && \
  git commit -m "chore: 添加 API 文档 submodule"

# 方式一:克隆时包含 submodule
git clone --recursive <project-url>

# 方式二:克隆后初始化 submodule
git clone <project-url>
cd project
git submodule update --init --recursive

# 1. 新成员入职:初始化环境(运行一次)
cd api-docs
./scripts/init-workspace.sh

# 2. 日常开发:每天开始前拉取最新文档
./scripts/update-docs.sh

# 3. 维护者:提交文档更新
./scripts/commit-docs.sh

# 1. 安装 Bruno (https://www.usebruno.com/downloads)
brew install bruno  # macOS
# 或下载安装包 (Windows/Linux)

# 2. 初始化文档环境
cd api-docs && ./scripts/init-workspace.sh

# 3. 配置 Claude Agent
# 创建 .claude/agents/bruno-api-documenter.md

# 4. 开始使用
# 在 Claude Code 中: @bruno-api-documenter.md 生成路由文档

#!/bin/bash

################################################################################
# 脚本名称: init-workspace.sh
# 功能描述: 新成员初始化本地工作环境
# 使用场景: 第一次克隆项目后,初始化 api-docs 工作分支
# 使用方法: ./scripts/init-workspace.sh
################################################################################

set -e  # 遇到错误立即退出

# 颜色定义
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
BLUE='\033[0;34m'
CYAN='\033[0;36m'
RED='\033[0;31m'
NC='\033[0m'

info() { echo -e "${BLUE}ℹ️  $1${NC}"; }
success() { echo -e "${GREEN}✅ $1${NC}"; }
warning() { echo -e "${YELLOW}⚠️  $1${NC}"; }
error() { echo -e "${RED}❌ $1${NC}"; }
highlight() { echo -e "${CYAN}📌 $1${NC}"; }

################################################################################
# 显示欢迎信息
################################################################################
clear
echo "========================================"
echo "  🚀 API 文档工作环境初始化"
echo "========================================"
echo ""

################################################################################
# 步骤 1: 检查 Git 仓库
################################################################################
info "检查 Git 仓库状态..."

if [ ! -d ".git" ]; then
    error "当前目录不是 Git 仓库"
    exit 1
fi

# 检查远程连接
if ! git remote get-url origin >/dev/null 2>&1; then
    error "未配置远程仓库 origin"
    exit 1
fi

success "Git 仓库检查通过"

################################################################################
# 步骤 2: 创建本地工作分支
################################################################################
info "创建本地工作分支 'local-workspace'..."

CURRENT_BRANCH=$(git branch --show-current)

if [ "$CURRENT_BRANCH" = "local-workspace" ]; then
    warning "已在 local-workspace 分支,跳过创建"
else
    # 检查分支是否已存在
    if git show-ref --verify --quiet refs/heads/local-workspace; then
        info "切换到已存在的 local-workspace 分支"
        git checkout local-workspace
    else
        # 确保有最新的 main 分支
        info "拉取最新的 main 分支..."
        git fetch origin main

        # 从 origin/main 创建新分支
        git checkout -b local-workspace origin/main
        success "已创建 local-workspace 分支"
    fi
fi

################################################################################
# 步骤 3: 配置分支跟踪
################################################################################
info "配置分支跟踪 origin/main..."

git branch --set-upstream-to=origin/main local-workspace
success "分支跟踪配置完成"

################################################################################
# 步骤 4: 配置 Git 推送策略
################################################################################
info "配置安全防护(防止意外推送)..."

# 设置当前分支不推送到远程
git config branch.local-workspace.pushRemote no_push

success "安全配置完成"

################################################################################
# 步骤 5: 显示使用指南
################################################################################
echo ""
echo "========================================"
success "初始化完成! 🎉"
echo "========================================"
echo ""
highlight "接下来你可以:"
echo ""
echo "1️⃣  在 Bruno 中打开文档:"
echo "   File > Open Collection > 选择当前目录"
echo ""
echo "2️⃣  随意修改 .bru 文件进行调试"
echo "   所有改动都在 local-workspace 分支,不会影响团队"
echo ""
echo "3️⃣  拉取团队更新:"
echo "   ./scripts/update-docs.sh"
echo ""
echo "4️⃣  如果你是维护者,需要提交文档:"
echo "   ./scripts/commit-docs.sh"
echo ""
warning "重要提示:"
echo "   • local-workspace 分支用于本地调试,不会推送到远程"
echo "   • 所有文档更新都通过 commit-docs.sh 提交到 main 分支"
echo "   • 不要手动执行 git push,使用脚本管理文档"
echo ""

#!/bin/bash

################################################################################
# 脚本名称: update-docs.sh
# 功能描述: 拉取团队更新的最新文档
# 使用场景: 每天开始工作前,同步最新的官方文档
# 使用方法: ./scripts/update-docs.sh
################################################################################

set -e

# 颜色定义
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
BLUE='\033[0;34m'
CYAN='\033[0;36m'
RED='\033[0;31m'
NC='\033[0m'

info() { echo -e "${BLUE}ℹ️  $1${NC}"; }
success() { echo -e "${GREEN}✅ $1${NC}"; }
warning() { echo -e "${YELLOW}⚠️  $1${NC}"; }
error() { echo -e "${RED}❌ $1${NC}"; }
highlight() { echo -e "${CYAN}📌 $1${NC}"; }

echo "========================================"
echo "  📥 更新官方 API 文档"
echo "========================================"
echo ""

################################################################################
# 步骤 1: 检查当前分支
################################################################################
CURRENT_BRANCH=$(git branch --show-current)

if [ "$CURRENT_BRANCH" != "local-workspace" ]; then
    warning "你不在 local-workspace 分支"
    echo "当前分支: $CURRENT_BRANCH"
    echo ""
    read -p "是否切换到 local-workspace 分支? (y/n) " -n 1 -r
    echo
    if [[ $REPLY =~ ^[Yy]$ ]]; then
        git checkout local-workspace
        success "已切换到 local-workspace 分支"
    else
        info "取消更新"
        exit 0
    fi
fi

################################################################################
# 步骤 2: 检查本地改动
################################################################################
info "检查本地改动..."

if ! git diff-index --quiet HEAD --; then
    warning "检测到本地有未提交的改动"
    echo ""
    git status --short
    echo ""
    highlight "请选择如何处理这些改动:"
    echo "  1) 暂存(stash)改动,更新后可以恢复"
    echo "  2) 提交改动到当前分支,然后合并更新"
    echo "  3) 丢弃所有改动,使用干净的官方文档"
    echo "  4) 取消更新"
    echo ""
    read -p "请选择 (1-4): " -n 1 -r
    echo ""

    case $REPLY in
        1)
            info "暂存本地改动..."
            git stash push -m "auto-stash-before-update-$(date +%Y%m%d-%H%M%S)"
            success "改动已暂存"
            STASHED=true
            ;;
        2)
            info "提交本地改动..."
            read -p "请输入提交信息: " commit_msg
            git add .
            git commit -m "$commit_msg"
            success "改动已提交"
            STASHED=false
            ;;
        3)
            warning "丢弃所有改动..."
            git reset --hard HEAD
            git clean -fd
            success "本地改动已丢弃"
            STASHED=false
            ;;
        4)
            info "取消更新"
            exit 0
            ;;
        *)
            error "无效选择"
            exit 1
            ;;
    esac
fi

################################################################################
# 步骤 3: 拉取最新文档
################################################################################
info "从 origin/main 拉取最新文档..."

if git pull origin main --no-edit; then
    success "文档更新成功"
else
    error "拉取失败,可能存在冲突"
    echo ""
    warning "解决方法:"
    echo "1. 查看冲突文件: git status"
    echo "2. 手动解决冲突"
    echo "3. 提交解决结果: git add . && git commit"
    exit 1
fi

################################################################################
# 步骤 4: 恢复暂存的改动(如果有)
################################################################################
if [ "$STASHED" = true ]; then
    echo ""
    read -p "是否恢复之前暂存的改动? (y/n) " -n 1 -r
    echo ""
    if [[ $REPLY =~ ^[Yy]$ ]]; then
        info "恢复暂存的改动..."
        if git stash pop; then
            success "改动已恢复"
        else
            warning "恢复时遇到冲突,请手动解决"
            echo "冲突文件列表:"
            git diff --name-only --diff-filter=U
        fi
    fi
fi

################################################################################
# 完成
################################################################################
echo ""
echo "========================================"
success "更新完成! 🎉"
echo "========================================"
echo ""
info "现在可以在 Bruno 中查看最新的文档了"

#!/bin/bash

################################################################################
# 脚本名称: commit-docs.sh
# 功能描述: 提交官方 API 文档更新到远程仓库（仅维护者使用）
# 使用场景: 当你修改了 API 文档模板并需要分享给团队其他成员时使用
# 使用方法: ./scripts/commit-docs.sh
# 权限要求: 需要有 api-docs 仓库的写权限
# 作者: Survey Team
################################################################################

set -e  # 遇到错误立即退出

# 颜色定义（用于终端输出）
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
BLUE='\033[0;34m'
CYAN='\033[0;36m'
NC='\033[0m' # No Color

# 打印带颜色的信息
info() {
    echo -e "${BLUE}ℹ️  $1${NC}"
}

success() {
    echo -e "${GREEN}✅ $1${NC}"
}

warning() {
    echo -e "${YELLOW}⚠️  $1${NC}"
}

error() {
    echo -e "${RED}❌ $1${NC}"
}

highlight() {
    echo -e "${CYAN}📌 $1${NC}"
}

################################################################################
# 步骤 1: 检查当前工作目录
################################################################################
info "检查当前工作目录..."

# 获取脚本所在目录的父目录（即 api-docs 根目录）
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
API_DOCS_DIR="$(dirname "$SCRIPT_DIR")"

# 切换到 api-docs 目录
cd "$API_DOCS_DIR"

# 验证是否在 git 仓库中（支持普通仓库和 submodule）
if ! git rev-parse --git-dir &>/dev/null; then
    error "当前目录不是 git 仓库！"
    exit 1
fi

success "当前工作目录: $API_DOCS_DIR"

################################################################################
# 步骤 2: 检查并切换到 main 分支
################################################################################
info "检查当前分支..."

CURRENT_BRANCH=$(git branch --show-current)
highlight "当前分支: $CURRENT_BRANCH"

if [[ "$CURRENT_BRANCH" != "main" ]]; then
    warning "你当前不在 main 分支上"
    warning "官方文档更新必须提交到 main 分支"
    echo ""

    # 特殊提示：如果在 local-workspace 分支
    if [[ "$CURRENT_BRANCH" == "local-workspace" ]]; then
        echo "========================================"
        highlight "检测到你在 local-workspace（个人调试分支）"
        echo "========================================"
        echo ""
        warning "local-workspace 分支用于个人调试，不应该推送到远程"
        warning "官方文档更新必须在 main 分支进行"
        echo ""
        echo "接下来将："
        echo "  1. 自动切换到 main 分支"
        echo "  2. 提交你的文档更新"
        echo "  3. 推送到远程仓库"
        echo "  4. 切回 local-workspace 分支并合并更新"
        echo ""
    fi

    # 检查当前分支是否有未提交的改动
    if [[ -n $(git status --porcelain) ]]; then
        echo "当前分支有未提交的改动："
        echo ""
        git status --short
        echo ""
        echo "请选择如何处理："
        echo "  1) 暂存(stash)改动，切换到 main 分支"
        echo "  2) 提交到当前分支，然后切换到 main 分支"
        echo "  3) 取消操作"
        echo ""
        read -p "请选择 (1-3): " choice

        case $choice in
            1)
                info "正在暂存当前改动..."
                STASH_NAME="临时暂存 - $(date '+%Y-%m-%d %H:%M:%S')"
                git stash push -m "$STASH_NAME"
                STASHED_FROM_BRANCH="$CURRENT_BRANCH"
                success "改动已暂存"
                ;;
            2)
                info "正在提交当前改动..."
                git add .
                echo ""
                read -p "请输入提交信息: " commit_msg
                git commit -m "$commit_msg"
                success "改动已提交到 $CURRENT_BRANCH 分支"
                ;;
            3)
                info "取消操作"
                exit 0
                ;;
            *)
                error "无效的选择"
                exit 1
                ;;
        esac
    fi

    # 切换到 main 分支
    info "正在切换到 main 分支..."
    git checkout main
    success "已切换到 main 分支"
fi

################################################################################
# 步骤 3: 同步远程最新内容
################################################################################
info "正在同步远程 main 分支最新内容..."

git fetch origin main

# 检查本地 main 是否落后于远程
LOCAL_COMMIT=$(git rev-parse main)
REMOTE_COMMIT=$(git rev-parse origin/main)

if [[ "$LOCAL_COMMIT" != "$REMOTE_COMMIT" ]]; then
    warning "本地 main 分支落后于远程分支"
    info "正在拉取最新内容..."

    if git pull origin main --rebase; then
        success "已同步远程最新内容"
    else
        error "拉取失败，可能存在冲突"
        echo ""
        warning "请手动解决冲突后重新运行此脚本"
        exit 1
    fi
else
    success "本地 main 分支已是最新"
fi

################################################################################
# 步骤 4: 检查待提交的改动
################################################################################
info "检查待提交的改动..."

# 如果没有改动，询问是否需要从其他分支合并
if [[ -z $(git status --porcelain) ]]; then
    warning "当前 main 分支没有未提交的改动"
    echo ""
    echo "可能的情况："
    echo "  1) 你在其他分支（如 local-workspace）做了修改，需要先合并到 main"
    echo "  2) 你还没有做任何修改"
    echo ""
    read -p "是否需要从其他分支合并改动？(y/n): " merge_from_branch

    if [[ "$merge_from_branch" == "y" ]]; then
        # 显示所有本地分支
        echo ""
        info "本地分支列表："
        git branch
        echo ""
        read -p "请输入要合并的分支名: " branch_to_merge

        # 验证分支是否存在
        if git show-ref --verify --quiet refs/heads/"$branch_to_merge"; then
            info "正在合并 $branch_to_merge 分支..."

            if git merge "$branch_to_merge" --no-ff -m "Merge branch '$branch_to_merge' into main"; then
                success "分支合并成功"
            else
                error "合并失败，请解决冲突后手动完成"
                exit 1
            fi
        else
            error "分支 $branch_to_merge 不存在"
            exit 1
        fi
    else
        info "没有改动需要提交，退出"
        exit 0
    fi
fi

################################################################################
# 步骤 5: 展示改动内容并确认
################################################################################
echo ""
echo "========================================"
info "待提交的改动："
echo "========================================"
echo ""

# 显示改动的文件
git status --short

# 添加到暂存区
git add .

echo ""
echo "========================================"
info "改动详情："
echo "========================================"
echo ""

# 显示详细的 diff（限制行数避免过长）
git diff --stat --cached

echo ""
read -p "是否查看完整的改动内容？(y/n): " show_full_diff

if [[ "$show_full_diff" == "y" ]]; then
    git diff --cached
fi

echo ""
warning "请仔细检查以上改动是否正确"
echo ""
read -p "确认提交这些改动到官方文档？(yes/no): " confirm_commit

if [[ "$confirm_commit" != "yes" ]]; then
    info "取消提交"
    exit 0
fi

################################################################################
# 步骤 6: 暂存改动（如果还没有暂存）
################################################################################
if [[ -n $(git status --porcelain | grep "^??") ]]; then
    info "发现未跟踪的文件，正在添加..."
    git add .
    success "文件已添加到暂存区"
elif [[ -n $(git status --porcelain | grep "^ M") ]]; then
    info "发现未暂存的修改，正在添加..."
    git add .
    success "修改已添加到暂存区"
fi

################################################################################
# 步骤 7: 输入提交信息
################################################################################
echo ""
highlight "请输入提交信息"
echo ""
echo "提交信息格式建议："
echo "  - docs: 更新 XXX API 文档"
echo "  - docs: 新增 XXX 接口文档"
echo "  - docs: 修复 XXX 文档参数错误"
echo "  - docs: 优化文档结构"
echo ""
read -p "提交信息: " commit_message

# 验证提交信息不为空
if [[ -z "$commit_message" ]]; then
    error "提交信息不能为空"
    exit 1
fi

################################################################################
# 步骤 8: 提交改动
################################################################################
info "正在提交改动..."

if git commit -m "$commit_message"; then
    success "改动已提交到本地仓库"
else
    error "提交失败"
    exit 1
fi

# 显示提交详情
echo ""
highlight "提交详情："
git log -1 --stat

################################################################################
# 步骤 9: 推送到远程仓库
################################################################################
echo ""
warning "即将推送到远程仓库，团队其他成员将看到这次更新"
echo ""
read -p "确认推送到远程仓库？(yes/no): " confirm_push

if [[ "$confirm_push" != "yes" ]]; then
    warning "已提交到本地，但未推送到远程"
    info "稍后可以手动推送: git push origin main"
    exit 0
fi

info "正在推送到远程仓库..."

if git push origin main; then
    success "推送成功！"
else
    error "推送失败"
    echo ""
    warning "可能的原因："
    echo "  1) 没有推送权限"
    echo "  2) 远程仓库有新的提交（需要先拉取）"
    echo "  3) 网络问题"
    echo ""
    info "改动已提交到本地，稍后可以手动推送: git push origin main"
    exit 1
fi

################################################################################
# 步骤 10: 切回原分支并合并更新（可选）
################################################################################
echo ""
success "官方文档已成功更新并推送！"
echo ""

if [[ "$CURRENT_BRANCH" != "main" ]] && [[ "$CURRENT_BRANCH" != "" ]]; then
    echo "你之前在 $CURRENT_BRANCH 分支上工作"
    read -p "是否切回 $CURRENT_BRANCH 分支并合并刚才的更新？(y/n): " switch_back

    if [[ "$switch_back" == "y" ]]; then
        info "正在切换到 $CURRENT_BRANCH 分支..."
        git checkout "$CURRENT_BRANCH"

        info "正在合并 main 分支的更新..."
        if git merge main; then
            success "已切回 $CURRENT_BRANCH 分支并合并了最新更新"
        else
            error "合并时发生冲突，请手动解决"
            exit 1
        fi

        # 如果之前有暂存，询问是否恢复
        if [[ -n "$STASHED_FROM_BRANCH" ]]; then
            echo ""
            read -p "是否恢复之前暂存的改动？(y/n): " restore_stash

            if [[ "$restore_stash" == "y" ]]; then
                if git stash pop; then
                    success "暂存的改动已恢复"
                else
                    error "恢复暂存时发生冲突，请手动解决"
                fi
            fi
        fi
    fi
fi

################################################################################
# 步骤 11: 显示完成摘要
################################################################################
echo ""
echo "========================================"
success "提交完成！"
echo "========================================"
echo ""
highlight "当前分支: $(git branch --show-current)"
highlight "最新提交: $(git log -1 --oneline)"
echo ""
info "团队其他成员可以通过以下命令获取更新："
echo "  cd api-docs"
echo "  ./scripts/update-docs.sh"
echo ""