周四技术文档：让AI帮你把代码变成人人能看懂的API文档

周四的文档困境

周二的功能写完了，周三联调通过了。

到了周四，产品经理来找你：“这个接口的文档能发一下吗？前端在等。”

你打开编辑器，看着自己上周写的代码——参数名记不清了，返回值结构忘了，边界情况没写注释。

写文档的痛苦在于：你刚写完代码，已经忘了自己写了什么。

这个Prompt帮你解决的是：从代码/接口描述直接生成专业级API文档，包括请求参数、响应格式、错误码、使用示例、最佳实践。

不需要你从零开始写。你只需要提供代码片段或接口定义，AI帮你整理成一份前端同事看得懂、后端同事觉得专业的文档。

核心模板：API文档生成器

把下面这段复制到 Claude 或 ChatGPT（推荐 Claude，对长文本和结构化输出支持更好）：

你是一位资深技术文档工程师，擅长为开发者编写清晰、完整、可直接使用的API文档。现在你是我的文档协作伙伴。

【项目背景】
- 项目名称：[如：用户中心服务 / 支付网关 / 内部数据平台]
- API框架：[如：Express.js / Spring Boot / FastAPI / Gin]
- 认证方式：[如：JWT Bearer Token / API Key / OAuth2]
- 目标读者：[前端开发 / 第三方开发者 / 内部团队]

【接口信息】
请从以下代码/描述中提取API信息并生成文档：

[粘贴你的代码片段、路由定义、Controller方法、或接口描述]

【文档要求】

第一部分：接口概述
- 用一句话说明这个接口是做什么的
- HTTP Method + URL路径
- 所属模块/资源
- 是否需要认证

第二部分：请求参数
- Path参数（如果有）
- Query参数（如果有）
- Request Body（JSON Schema格式，标注必填/选填、类型、默认值、示例值）
- Headers（除了标准Header外的自定义Header）
- 每个参数都要有中文说明

第三部分：响应格式
- 成功响应（HTTP 200/201/204）
  - JSON结构示例（完整的、可直接复制使用的示例）
  - 每个字段的类型和含义
- 错误响应
  - 常见错误码列表（HTTP状态码 + 业务错误码）
  - 每个错误码的含义和排查建议

第四部分：使用示例
- cURL命令示例（可直接在终端运行）
- JavaScript/Fetch示例（如果目标读者是前端）
- Python/Requests示例（如果目标读者包含后端）

第五部分：注意事项
- 速率限制（如果有）
- 特殊格式要求（如日期格式、文件大小限制）
- 已知限制和边界情况
- 常见踩坑点

【输出格式】
- 使用Markdown格式
- 代码块标注语言类型
- 参数表格清晰易读
- 示例代码可以直接复制运行
- 中文为主，技术术语保留英文原文

三种高频场景变体

变体一：从现有代码生成文档

你已经写好了Controller或服务层代码，需要补文档。

以下是我写的接口代码：

【文件路径】
[src/controllers/user.ts]

【代码内容】
[粘贴完整的Controller方法代码]

请帮我生成这份接口的完整API文档，要求：
1. 从代码注释、类型定义、参数名中自动推断字段含义
2. 如果没有注释，根据变量名和上下文合理推测并标注「待确认」
3. 生成可直接运行的cURL示例
4. 补充代码中可能遗漏的错误处理场景
5. 输出格式参考OpenAPI/Swagger的文档风格

变体二：从接口定义生成文档

你只有接口设计（Swagger/YAML/JSON），还没有写代码。

我有一个接口设计，请帮我生成对应的API文档：

【接口定义】
[粘贴Swagger YAML / OpenAPI JSON / 接口描述文档]

【补充信息】
- 业务背景：[如：用户注册接口，用于新用户创建账号]
- 目标读者：[如：前端开发，需要知道传什么参数、拿什么数据]
- 特殊要求：[如：需要包含前端集成示例、需要标注字段校验规则]

请生成一份面向前端的API文档，重点放在：
1. 参数怎么传（表单/JSON/Query）
2. 返回什么数据
3. 出错怎么办
4. 前端怎么调用（附Fetch/Axios示例）

变体三：批量生成一组接口文档

你需要为整个模块生成文档。

我需要为以下接口列表生成统一格式的文档：

【接口列表】
1. GET /api/v1/users - 获取用户列表
2. POST /api/v1/users - 创建用户
3. PUT /api/v1/users/:id - 更新用户
4. DELETE /api/v1/users/:id - 删除用户
5. GET /api/v1/users/:id/profile - 获取用户资料

【公共信息】
- 基础URL：https://api.example.com
- 认证：Bearer Token放在Authorization Header
- 统一响应格式：{ code, message, data }
- 分页参数：page, pageSize

请先帮我生成接口概览表（所有接口的Method、URL、简要说明），然后逐个生成详细文档。

输出要求：
- 所有接口使用一致的文档格式
- 公共参数只写一次，引用即可
- 每个接口独立成小节，方便后续维护

快速版（5分钟搞定）

赶时间？用这个精简版：

帮我把这段代码转成API文档：

[粘贴代码]

需要包含：
1. 接口说明（一句话）
2. 请求参数表格
3. 响应示例（JSON）
4. 一个curl示例
5. 注意事项（2-3条）

格式要清晰，让前端同事能直接照着调用。

使用技巧

从OpenAPI/Swagger反向生成文档。 如果你的项目已经有Swagger定义，直接把YAML文件内容贴给AI，让它生成面向人类的文档——比Swagger UI好看多了。

让AI当你的"读者测试员"。 文档写完后，加一句"假设你是一个完全不懂这个项目的前端开发，看完这份文档能否独立完成对接？如果不能，缺了什么？“这能帮你发现文档里的盲点。

版本管理很重要。 每次接口变更，用同一个模板重新生成文档。对比两版差异，就能清楚看到改了什么。建议把生成的文档存到Git里，和代码一起维护。

示例代码要能跑。 很多文档的示例代码复制过去就跑不通——因为少了认证头、用了错误的Content-Type、或者参数格式不对。让AI生成的示例尽量贴近真实调用场景。

错误文档比成功文档更重要。 开发者最需要的不是"正常情况返回什么”，而是"出错了怎么办"。优先完善错误码说明和排查建议。

保持文档和代码同步。 最好的文档策略是"代码即文档"——在代码注释里写清楚，让AI定期从注释生成文档。这样改代码的时候自然就把文档也更新了。

效果示例

输入（代码片段）：

// src/controllers/order.ts
@Post('/orders')
async createOrder(@Body() dto: CreateOrderDto) {
  const order = this.orderService.create({
    userId: dto.userId,
    items: dto.items.map(item => ({
      productId: item.productId,
      quantity: item.quantity,
      price: item.price
    })),
    totalAmount: dto.totalAmount,
    shippingAddress: dto.shippingAddress
  });
  
  if (!order) {
    throw new BadRequestException('创建订单失败');
  }
  
  return {
    code: 200,
    message: '订单创建成功',
    data: order
  };
}

AI输出：

创建订单

POST /api/orders

创建一个新的订单。需要提供用户ID、商品列表、总金额和收货地址。

认证要求

需要在请求头中携带 Authorization: Bearer <token>。

请求体

成功响应

HTTP 200

{
  "code": 200,
  "message": "订单创建成功",
  "data": {
    "id": "ord_20240725001",
    "userId": "user_123",
    "items": [
      {
        "productId": "prod_456",
        "quantity": 2,
        "price": 99.00
      }
    ],
    "totalAmount": 198.00,
    "status": "pending",
    "createdAt": "2024-07-25T10:30:00Z"
  }
}

错误响应

调用示例

cURL：

curl -X POST https://api.example.com/orders \
  -H "Authorization: Bearer your_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "user_123",
    "items": [
      {
        "productId": "prod_456",
        "quantity": 2,
        "price": 99.00
      }
    ],
    "totalAmount": 198.00,
    "shippingAddress": {
      "province": "广东省",
      "city": "深圳市",
      "detail": "南山区科技园XX路XX号"
    }
  }'

JavaScript (Fetch)：

const response = await fetch('https://api.example.com/orders', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer your_token_here',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    userId: 'user_123',
    items: [
      { productId: 'prod_456', quantity: 2, price: 99.00 }
    ],
    totalAmount: 198.00,
    shippingAddress: {
      province: '广东省',
      city: '深圳市',
      detail: '南山区科技园XX路XX号'
    }
  })
});
const result = await response.json();
console.log(result);

注意事项

• totalAmount 需要与 items 中各商品 price × quantity 的总和一致，否则可能被拒绝
• 收货地址的省市区建议使用标准行政区划编码
• 订单创建后状态为 pending，需要等待支付流程完成

组合使用技巧

API文档 + Code Review 联动

用 code-review-prompt 模板审查接口代码，确保逻辑正确；再用本文档模板生成文档，确保对外说明清晰。两个步骤分开做，质量更高。

API文档 + 前端 Mock 联动

生成文档的同时，让AI基于文档生成Mock Server配置或Postman Collection。前端可以拿着Mock数据先开发，不用等后端真正上线。

API文档 + 测试用例联动

文档里的请求参数和响应格式，可以直接转化为测试用例。让AI根据生成的文档再输出一份测试计划，覆盖正常路径和异常路径。

什么时候用这个模板

• 新功能上线前，需要给前端提供对接文档
• 接口变更了，但文档没更新，被同事催
• 新加入的团队成员需要了解现有接口
• 第三方对接需要对外发布API文档
• 代码review时发现接口缺少必要的注释和文档

进阶用法

自动生成OpenAPI规范。 让AI根据代码生成标准的OpenAPI 3.0 YAML文件，可以直接导入Swagger UI或Postman。

基于上面的API文档，帮我生成一份OpenAPI 3.0规范的YAML文件，
包含paths、components、securityScheme的定义。

批量接口文档索引。 当接口超过10个时，让AI先生成一个索引页，列出所有接口的URL、Method、简述，每个接口链接到详细文档。

文档版本对比。 每次接口变更后重新生成文档，让AI对比新旧版本的差异，自动生成变更日志。

什么时候不该用

• 接口极其简单（CRUD基本操作）：如果只是标准的增删改查，Swagger UI就够了，不用额外生成文档。
• 代码还没写完：等接口逻辑稳定后再生成文档。频繁变动的接口不适合提前写文档。
• 涉及敏感业务逻辑：如果接口包含核心算法或商业机密，文档要脱敏后再给外部看。
• 你已经有完善的文档系统：如果用Confluence/Notion管理文档，让AI生成内容后你手动整理到系统中，而不是直接复制粘贴。

写在最后

好的API文档不是写出来的，是改出来的。

第一次生成的文档不可能完美——参数描述不够准确、示例不够全面、错误场景没覆盖全。但这没关系。先用AI生成一个80分的版本，然后在实际对接中逐步完善它。

比"永远不开始"更好的策略是"先有一个粗糙的版本"。

下次前端催你要文档的时候，别慌。把代码丢进这个模板，5分钟后你就能交差了。