案例 003：用 Agent 生成和维护 OpenAPI 文档

┌────────────────────────────────────────────────────────────┐
│                   OpenAPI 文档自动化流程                     │
│                                                            │
│  ┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────┐ │
│  │ 源码扫描  │──▶│ 文档生成  │──▶│ 差异检测  │──▶│ 审查  │ │
│  │ (AST)    │    │ (OpenAPI)│    │ (Diff)   │    │(Agent)│ │
│  └──────────┘    └──────────┘    └──────────┘    └──┬───┘ │
│                                                      │     │
│                                               ┌──────▼───┐ │
│                                               │ PR 评论   │ │
│                                               │ + 自动发布│ │
│                                               └──────────┘ │
└────────────────────────────────────────────────────────────┘

# openapi-scan-config.yaml
scan:
  # 扫描目标
  targets:
    - service: "user-service"
      source: "src/controllers/**/*.ts"
      decorator: "@ApiOperation"      # NestJS Swagger 装饰器
      base_path: "/api/v1"
    
    - service: "order-service"
      source: "src/handlers/**/*.py"
      decorator: "@router"            # FastAPI 路由装饰器
      base_path: "/api/v1"

  # 提取规则
  extract:
    summary: "从 @ApiOperation(summary=...) 提取"
    description: "从函数 docstring 提取"
    request_body: "从 DTO 类型定义提取"
    response: "从返回值类型 + @ApiResponse 提取"
    parameters: "从路由参数 + @Param 提取"
    authentication: "从 @UseGuards(AuthGuard) 推断"

  # 输出
  output:
    format: "openapi-3.1"
    path: "docs/openapi/{service}.yaml"
    group_by: "tag"                   # 按模块分组

name: "OpenAPI 文档生成"
prompt: |
  你是一个 API 文档工程师。扫描以下源码，生成完整的 OpenAPI 3.1 文档。

  ## 输入
  - 控制器源码：{{controller_source}}
  - DTO 定义：{{dto_source}}
  - 已有文档（用于 diff）：{{existing_doc}}

  ## 任务
  1. 扫描所有路由端点，提取：路径、方法、参数、请求体、响应
  2. 从函数名和注释推断 summary 和 description
  3. 为每个端点生成示例请求和响应
  4. 标注已废弃的端点（有 @Deprecated 装饰器或注释中包含"废弃"）
  5. 为所有错误码生成 response 定义

  ## 输出
  - 完整的 OpenAPI YAML 文件
  - 与上一版本的 diff 报告（新增/修改/删除了哪些端点）

# scripts/openapi-diff.py
"""
比较两个版本的 OpenAPI 文档，生成差异报告。
差异级别：
- BREAKING: 破坏性变更（删除端点、修改参数类型、删除必填参数）
- NON_BREAKING: 非破坏性变更（新增端点、新增可选参数）
- DEPRECATION: 废弃标记
"""
import yaml
import json
import sys
from deepdiff import DeepDiff

def load_spec(path):
    with open(path) as f:
        return yaml.safe_load(f)

def extract_endpoints(spec):
    """提取所有端点，标准化为 {method:path} -> endpoint_info"""
    endpoints = {}
    for path, methods in spec.get("paths", {}).items():
        for method in ["get", "post", "put", "patch", "delete"]:
            if method in methods:
                key = f"{method.upper()} {path}"
                endpoints[key] = methods[method]
    return endpoints

def compare_specs(old_path, new_path):
    old_spec = load_spec(old_path)
    new_spec = load_spec(new_path)
    
    old_endpoints = extract_endpoints(old_spec)
    new_endpoints = extract_endpoints(new_spec)
    
    changes = []
    
    # 检测删除的端点（破坏性）
    for key in old_endpoints:
        if key not in new_endpoints:
            changes.append({
                "level": "BREAKING",
                "type": "endpoint_removed",
                "endpoint": key,
                "message": f"端点 {key} 已被删除",
            })
    
    # 检测新增的端点
    for key in new_endpoints:
        if key not in old_endpoints:
            changes.append({
                "level": "NON_BREAKING",
                "type": "endpoint_added",
                "endpoint": key,
                "message": f"新增端点 {key}",
            })
    
    # 检测修改的端点
    for key in old_endpoints:
        if key in new_endpoints:
            old_ep = old_endpoints[key]
            new_ep = new_endpoints[key]
            
            # 检查参数变化
            old_params = {p["name"]: p for p in old_ep.get("parameters", [])}
            new_params = {p["name"]: p for p in new_ep.get("parameters", [])}
            
            for name in old_params:
                if name not in new_params:
                    changes.append({
                        "level": "BREAKING",
                        "type": "parameter_removed",
                        "endpoint": key,
                        "parameter": name,
                        "message": f"{key}: 参数 {name} 已被删除",
                    })
            
            for name in new_params:
                if name not in old_params:
                    required = new_params[name].get("required", False)
                    changes.append({
                        "level": "BREAKING" if required else "NON_BREAKING",
                        "type": "parameter_added",
                        "endpoint": key,
                        "parameter": name,
                        "message": f"{key}: {'新增必填' if required else '新增可选'}参数 {name}",
                    })
            
            # 检查废弃标记
            if new_ep.get("deprecated") and not old_ep.get("deprecated"):
                changes.append({
                    "level": "DEPRECATION",
                    "type": "endpoint_deprecated",
                    "endpoint": key,
                    "message": f"端点 {key} 已标记为废弃",
                })
    
    return changes

def format_report(changes):
    """生成 Markdown 格式的差异报告"""
    breaking = [c for c in changes if c["level"] == "BREAKING"]
    non_breaking = [c for c in changes if c["level"] == "NON_BREAKING"]
    deprecations = [c for c in changes if c["level"] == "DEPRECATION"]
    
    report = ["# OpenAPI 差异报告\n"]
    
    if breaking:
        report.append(f"## 🔴 破坏性变更（{len(breaking)} 项）\n")
        for c in breaking:
            report.append(f"- **{c['endpoint']}**: {c['message']}")
        report.append("")
    
    if deprecations:
        report.append(f"## 🟡 废弃标记（{len(deprecations)} 项）\n")
        for c in deprecations:
            report.append(f"- **{c['endpoint']}**: {c['message']}")
        report.append("")
    
    if non_breaking:
        report.append(f"## 🟢 非破坏性变更（{len(non_breaking)} 项）\n")
        for c in non_breaking:
            report.append(f"- **{c['endpoint']}**: {c['message']}")
        report.append("")
    
    if not changes:
        report.append("✅ 无变更")
    
    return "\n".join(report)

if __name__ == "__main__":
    old_path, new_path = sys.argv[1], sys.argv[2]
    changes = compare_specs(old_path, new_path)
    print(format_report(changes))
    
    # 如果有破坏性变更，退出码为 1（CI 会阻断）
    has_breaking = any(c["level"] == "BREAKING" for c in changes)
    sys.exit(1 if has_breaking else 0)

# .github/workflows/openapi-docs.yml
name: OpenAPI 文档自动化

on:
  pull_request:
    paths:
      - "src/controllers/**"
      - "src/handlers/**"
      - "src/dto/**"
      - "src/schemas/**"

jobs:
  generate-and-diff:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 2  # 需要上一版本做 diff

      - name: 生成新版 OpenAPI 文档
        run: |
          npm run openapi:generate
          cp docs/openapi/user-service.yaml /tmp/new-spec.yaml

      - name: 获取旧版文档
        run: |
          git show HEAD~1:docs/openapi/user-service.yaml > /tmp/old-spec.yaml || \
          echo "{}" > /tmp/old-spec.yaml

      - name: 差异检测
        id: diff
        run: |
          python scripts/openapi-diff.py /tmp/old-spec.yaml /tmp/new-spec.yaml > diff-report.md
          echo "has_breaking=$?" >> $GITHUB_OUTPUT

      - name: Agent 审查文档质量
        run: |
          node scripts/agent-review-docs.js /tmp/new-spec.yaml >> review.md

      - name: PR 评论
        uses: actions/github-script@v7
        with:
          script: |
            const fs = require('fs');
            const diff = fs.readFileSync('diff-report.md', 'utf-8');
            const review = fs.readFileSync('review.md', 'utf-8');
            await github.rest.issues.createComment({
              owner: context.repo.owner,
              repo: context.repo.repo,
              issue_number: context.issue.number,
              body: `## OpenAPI 文档变更报告\n\n${diff}\n\n## Agent 质量审查\n\n${review}`
            });

      - name: 破坏性变更阻断
        if: steps.diff.outputs.has_breaking == '1'
        run: |
          echo "❌ 检测到破坏性 API 变更，需要 Tech Lead 审批"
          exit 1

  publish:
    needs: generate-and-diff
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: 生成并发布文档
        run: |
          npm run openapi:generate
          npm run docs:build
      - name: 部署到文档站点
        run: |
          aws s3 sync docs/dist/ s3://api-docs-bucket/
          aws cloudfront create-invalidation --distribution-id $DIST_ID --paths "/*"

# agent-doc-review.yaml
name: "OpenAPI 文档质量审查"
prompt: |
  你是 API 文档审查专家。审查以下 OpenAPI 文档的质量。

  ## 审查清单
  1. **完整性**：每个端点是否有 summary、description、示例请求、示例响应？
  2. **错误码**：是否覆盖了常见错误（400/401/403/404/500）？
  3. **参数描述**：每个参数是否有类型、是否必填、默认值、取值范围？
  4. **命名一致性**：字段命名是否遵循项目规范（camelCase / snake_case）？
  5. **废弃标记**：是否有缺少废弃说明的 deprecated 端点？

  ## 输出
  按以下 JSON 格式输出审查结果：
  {
    "score": 0-100,
    "issues": [{"severity": "HIGH|MEDIUM|LOW", "endpoint": "", "message": ""}],
    "recommendations": []
  }