Claude 自动生成 API 文档：从代码注释到完整文档

写在前面

API文档是团队协作的基础设施，也是每个后端开发者心里的一块石头。接口一直在改，文档总是落后；前端来问接口格式，只能让他们看代码或者靠口头解释；外部对接方接入时，文档残缺不全，沟通成本极高。

维护文档难，不是因为开发者懒，而是因为写代码和写文档是两件事，工程师同时做好两件事的认知负担太高了。

Claude 4.6能把这个问题解决大半：你只需要维护好代码，文档的事交给它。

方案一：从代码直接生成API文档

最直接的用法，把代码粘贴给Claude，让它生成文档：

以下是我的订单管理API接口代码（Express + TypeScript），
请生成完整的API文档：

要求：
- OpenAPI 3.0 格式（YAML）
- 包含所有接口的路径、方法、参数说明、请求体、响应结构
- 添加合理的接口描述
- 标注必填/可选参数
- 添加示例值

[粘贴路由和Controller代码]

Claude会分析你的代码，自动提取：
– 路由路径和HTTP方法
– 路径参数、查询参数
– 请求体结构（从Zod Schema或TypeScript类型推断）
– 响应数据结构（从返回值类型推断）
– 已有的JSDoc注释内容

方案二：从现有OpenAPI规范生成用户文档

OpenAPI规范是机器读的，给人类看的文档还需要更多解释。让Claude把机器语言转化为人类友好的文档：

这是我们API的OpenAPI规范文件：
[粘贴openapi.yaml内容]

请生成两份文档：

1. 快速开始指南（给第一次接入的开发者）：
   - 认证方式（如何获取和使用Token）
   - 5分钟能跑通的Hello World示例
   - 最常用的3个接口

2. 完整接口文档（Markdown格式）：
   - 按功能模块分组
   - 每个接口：描述、URL、认证要求、参数表格、响应示例
   - 错误码说明
   - 使用curl、Python、JavaScript的代码示例

方案三：生成多语言代码示例

API文档最有价值的部分往往是代码示例。让Claude批量生成：

为以下API接口生成代码示例：

接口：POST /api/v1/orders/create
认证：Bearer Token（在Authorization header里）
请求体：
{
  "items": [
    { "product_id": 123, "quantity": 2 }
  ],
  "shipping_address_id": 456
}
成功响应：
{
  "code": 0,
  "data": {
    "order_id": "ORD-2026041001",
    "total_amount": 199.00,
    "status": "pending_payment"
  }
}

请生成以下语言的完整调用示例：
1. curl（包含完整的命令行参数）
2. Python（使用requests库）
3. JavaScript（使用fetch API）
4. Java（使用OkHttp）
5. Go（使用标准库net/http）

每个示例要完整可运行，包含错误处理。

方案四：文档审查和补全

已有文档，但不确定是否完整？让Claude做审查：

这是我们当前的API文档，请帮我审查：
[粘贴现有文档]

审查要点：
1. 哪些接口的文档描述不清晰（模糊、不准确）
2. 哪些接口缺少请求/响应示例
3. 错误码是否完整（有没有接口可能返回但没有文档的错误）
4. 认证方式说明是否清楚
5. 参数校验规则是否都有说明

对每个问题，给出具体的改进建议。

方案五：Webhook文档生成

Webhook文档比普通REST API文档更难写，因为要描述异步事件的触发时机和数据格式：

我们有一套Webhook系统，当以下事件发生时会向用户配置的URL发送POST请求：
- order.created：用户下单
- order.paid：订单支付成功
- order.shipped：订单发货
- order.completed：订单完成
- order.cancelled：订单取消

每个事件的payload结构如下：
[描述数据结构]

请生成完整的Webhook接入文档，包括：
1. 什么是Webhook，为什么要用它（面向不熟悉的开发者）
2. 如何配置Webhook接收地址
3. 签名验证机制（用于验证请求来源）
4. 每个事件的触发条件和payload示例
5. 最佳实践（幂等性处理、异步处理、失败重试）
6. 用Python/Node.js实现Webhook接收端的示例代码

方案六：变更日志生成

版本迭代时，自动生成API变更日志：

我们即将发布API v2版本，相比v1有以下变化：
- 新增：POST /api/v2/orders/batch-create（批量创建订单）
- 修改：GET /api/v2/orders 新增了 category_id 筛选参数
- 废弃：DELETE /api/v1/orders/:id（改为 POST /api/v2/orders/:id/cancel）
- 移除：GET /api/v1/users/info 替代为 GET /api/v2/users/profile

请生成：
1. 用户友好的迁移指南（从v1升级到v2）
2. 每个变更的影响分析和迁移代码示例
3. 标准格式的CHANGELOG条目

集成到CI/CD流程

把文档生成集成到开发流程里，实现”代码提交 → 文档自动更新”：

# 示例：在CI流程里自动更新API文档
import anthropic
import subprocess
import json

def get_changed_files():
    """获取本次提交修改的文件"""
    result = subprocess.run(
        ['git', 'diff', '--name-only', 'HEAD~1', 'HEAD'],
        capture_output=True, text=True
    )
    return result.stdout.strip().split('n')

def update_api_docs(changed_routes):
    """为修改的路由文件更新文档"""
    client = anthropic.Anthropic(
        api_key="your-code80-api-key",
        base_url="https://code.ai80.vip"
    )

    for route_file in changed_routes:
        with open(route_file, 'r') as f:
            code = f.read()

        response = client.messages.create(
            model="claude-sonnet-4-6",
            max_tokens=2048,
            messages=[{
                "role": "user",
                "content": f"为以下API路由更新OpenAPI文档片段：nn{code}"
            }]
        )

        # 将结果写入对应的文档文件
        doc_file = route_file.replace('routes/', 'docs/').replace('.ts', '.yaml')
        with open(doc_file, 'w') as f:
            f.write(response.content[0].text)

# 检查是否有路由文件变更
changed = get_changed_files()
changed_routes = [f for f in changed if 'routes/' in f and f.endswith('.ts')]

if changed_routes:
    update_api_docs(changed_routes)
    print(f"已更新 {len(changed_routes)} 个文档文件")

生成SDK文档

如果你提供了SDK，让Claude同时生成SDK文档：

这是我们的Python SDK核心代码：
[粘贴SDK代码]

请生成SDK文档，包括：
1. 安装方式（pip install）
2. 快速开始（5行代码的示例）
3. 每个主要类和方法的文档（参数、返回值、示例）
4. 常用工作流示例（端到端的完整场景）
5. 错误处理指南
6. 配置项说明

风格要求：类似Stripe或Twilio的SDK文档风格，代码示例为主，文字为辅。

怎么用上Claude 4.6

网页版（claude.ai）直接用于日常的文档生成任务。Claude Pro订阅（$20/月）可以处理更长的代码文件。

如果要集成到自动化流程（CI/CD、文档平台），需要通过API调用。国内开发者可以通过 Code80 接入，支持国内支付，修改base_url参数即可：

import anthropic

client = anthropic.Anthropic(
    api_key="your-code80-api-key",
    base_url="https://code.ai80.vip"
)

详情：code.ai80.vip

常见问题

Q：Claude生成的OpenAPI规范准确吗？能直接用在Swagger UI里吗？
A：生成的规范通常是语法正确的，可以直接在Swagger UI里渲染。但需要检查：路径参数的描述是否准确、响应Schema是否完整、必填字段是否正确标注。第一次生成后做一次人工复核，后续迭代就快很多了。

Q：文档更新跟不上代码更新怎么办？
A：最实用的方案是把文档生成加进Code Review流程——每次修改API的PR，要求同时更新文档。Claude可以帮你快速生成文档diff，降低这一步的工作量。

Q：能生成中文文档吗？
A：完全可以。在要求里加上”请用中文生成”即可。Claude对中英文技术文档的生成质量都很高，混合使用（技术术语保持英文，说明文字用中文）也没问题。

Q：我们的API有几百个接口，一次性能处理吗？
A：建议分模块处理，每次给Claude 20-30个接口的代码，生成对应的文档片段，最后汇总。一次性给几百个接口容易超出上下文限制，而且质量会下降。