AI 文档生成：API 文档/技术文档/用户手册自动化

# 原始代码
@app.route('/api/v2/orders', methods=['POST'])
@validate_schema(OrderSchema)
@rate_limit(100, per='minute')
def create_order():
    """创建新订单
    
    Args:
        body: OrderCreateRequest - 订单创建请求
            - product_id: str (required) - 商品ID
            - quantity: int (required) - 数量，1-99
            - coupon_code: str (optional) - 优惠券码
    
    Returns:
        201: OrderResponse - 创建成功
            - order_id: str - 订单ID
            - total_price: float - 总价
            - status: str - 订单状态
        400: ErrorResponse - 参数错误
        409: ErrorResponse - 库存不足
    
    Raises:
        RateLimitExceeded: 超过调用频率
        InsufficientStock: 库存不足
    """
    ...

## 创建订单

`POST /api/v2/orders`

创建一个新的订单。

### 请求体

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| product_id | string | ✅ | 商品ID |
| quantity | integer | ✅ | 数量，范围1-99 |
| coupon_code | string | ❌ | 优惠券码 |

### 响应

#### 201 Created
```json
{
  "order_id": "ORD-2026-0628-001",
  "total_price": 299.00,
  "status": "pending"
}

{
  "error": "INVALID_QUANTITY",
  "message": "数量必须在1-99之间"
}

{
  "error": "INSUFFICIENT_STOCK",
  "message": "商品库存不足"
}

curl -X POST https://api.example.com/v2/orders \
  -H "Content-Type: application/json" \
  -d '{"product_id": "PROD-001", "quantity": 2}'

### 2.2 主流工具对比

| 工具 | 输入源 | 输出格式 | 特色 |
|------|--------|----------|------|
| Mintlify | 代码注释+OpenAPI | MDX网站 | 自动生成交互式API文档 |
| ReadMe AI | OpenAPI/GraphQL | 在线文档 | 自动示例+API Explorer |
| Bump.sh | OpenAPI/AsyncAPI | 版本化文档 | 变更Diff可视化 |
| Stoplight | OpenAPI | 完整API门户 | 设计优先+Mock服务 |
| Swimm | 代码库 | 文档+代码同步 | 代码与文档关联验证 |

### 2.3 CI/CD集成

```yaml
# GitHub Actions: API文档自动生成
name: Generate API Docs
on:
  push:
    paths:
      - 'src/api/**'
      - 'docs/openapi.yaml'

jobs:
  generate-docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      # 1. 从代码提取OpenAPI规范
      - name: Extract OpenAPI Spec
        run: npx @redocly/cli bundle docs/openapi.yaml --output dist/openapi.yaml
      
      # 2. AI增强文档
      - name: AI Enhance Documentation
        run: |
          npx mintlify enhance \
            --spec dist/openapi.yaml \
            --output dist/enhanced.yaml \
            --add-examples \
            --add-descriptions \
            --add-error-codes
      
      # 3. 检查Breaking Changes
      - name: Check Breaking Changes
        run: |
          npx bump diff \
            --old ${{ github.event.before }} \
            --new dist/openapi.yaml \
            --format markdown > breaking-changes.md
      
      # 4. 发布文档
      - name: Deploy Docs
        run: npx mintlify deploy dist/

# AI分析代码库生成架构文档
def generate_architecture_doc(repo_path):
    # 1. 分析项目结构
    structure = analyze_project_structure(repo_path)
    
    # 2. 识别模块和依赖关系
    modules = identify_modules(repo_path)
    dependencies = analyze_dependencies(modules)
    
    # 3. 生成Mermaid架构图
    diagram = generate_mermaid_architecture(modules, dependencies)
    
    # 4. AI生成文档
    doc = llm.generate(f"""
    基于以下信息生成技术架构文档：
    
    项目结构：{structure}
    模块列表：{modules}
    依赖关系：{dependencies}
    
    文档需包含：
    1. 系统概述
    2. 架构图（Mermaid）
    3. 模块说明
    4. 数据流图
    5. 技术选型说明
    """)
    
    return doc

# 原始代码（无注释）
def process_refund(order_id, amount, reason):
    order = db.get_order(order_id)
    if order.status != 'completed':
        raise InvalidOrderStatus()
    if amount > order.total_price:
        raise RefundExceedsTotal()
    refund = Refund(order=order, amount=amount, reason=reason)
    refund.save()
    notify_service.send(order.user_id, 'refund_processed', {
        'amount': amount,
        'order_id': order_id
    })
    return refund

# AI生成的注释
def process_refund(order_id: str, amount: float, reason: str) -> Refund:
    """处理订单退款
    
    为已完成订单创建退款记录，并通知用户。退款金额不能超过
    订单总金额。
    
    Args:
        order_id: 要退款的订单ID
        amount: 退款金额（必须≤订单总额）
        reason: 退款原因
    
    Returns:
        Refund: 创建的退款记录对象
    
    Raises:
        InvalidOrderStatus: 订单状态不是'completed'时抛出
        RefundExceedsTotal: 退款金额超过订单总额时抛出
    
    Side Effects:
        - 向用户发送退款处理通知
        - 数据库写入退款记录
    
    Example:
        >>> refund = process_refund('ORD-001', 99.00, '质量问题')
        >>> refund.status
        'pending'
    """

技术描述（开发者输入）：
"系统支持通过Webhook接收订单状态变更通知，需要在设置页面配置
回调URL，支持HMAC-SHA256签名验证，重试策略为3次指数退避"

AI转化为用户手册：
## 订单状态通知

当订单状态发生变化（如已发货、已签收）时，系统会自动向您配置的
地址发送通知。

### 如何设置通知？

1. 进入 **设置** > **通知配置**
2. 在"回调地址"栏填写接收通知的URL
3. 点击"生成密钥"获取签名验证密钥
4. 点击保存

### 通知发送频率

如果通知未能成功送达，系统会自动重试：
- 第1次重试：1分钟后
- 第2次重试：5分钟后
- 第3次重试：30分钟后

超过3次后不再重试，可在通知记录中手动重发。

# 自动截图流程
def generate_screenshots(user_flow):
    browser = launch_browser()
    
    for step in user_flow.steps:
        # 执行操作
        browser.execute(step.action)
        
        # 智能截图（等待关键元素加载）
        browser.wait_for(step.screenshot_element)
        screenshot = browser.screenshot()
        
        # AI标注关键区域
        annotated = ai.annotate_screenshot(
            screenshot, 
            highlight=step.highlight_area,
            label=step.annotation
        )
        
        save(annotated, f"images/{step.id}.png")

# 检测文档与代码的不一致
class DocSyncChecker:
    def check(self, docs, code):
        issues = []
        
        for doc in docs:
            # 1. 检查代码引用是否有效
            for code_ref in doc.code_references:
                if not self.code_exists(code_ref):
                    issues.append({
                        'type': 'stale_reference',
                        'doc': doc.path,
                        'ref': code_ref,
                        'message': f'引用的代码不存在: {code_ref}'
                    })
            
            # 2. 检查API签名是否变更
            for api in doc.api_references:
                current = self.get_current_api(api)
                if current != api.signature:
                    issues.append({
                        'type': 'api_changed',
                        'doc': doc.path,
                        'old': api.signature,
                        'new': current
                    })
            
            # 3. LLM检查语义一致性
            semantic_check = llm.verify_consistency(doc, code)
            if semantic_check.issues:
                issues.extend(semantic_check.issues)
        
        return issues

git-cliff + AI 增强的变更日志生成：

## [2.5.0] - 2026-06-28

### ✨ 新功能
- 订单退款API新增`partial_refund`参数，支持部分退款 (#234)
- 用户搜索支持模糊匹配和拼音搜索 (#241)

### 🐛 Bug修复  
- 修复高并发下库存超卖问题 (#238)
- 修复优惠券叠加计算错误 (#245)

### ⚠️ 破坏性变更
- `POST /api/v1/orders` 响应字段`price`重命名为`total_price`
- 最低Node.js版本要求从16提升到18

### 📚 文档
- 更新API认证文档
- 新增Webhook集成指南