实战案例：用提示词30分钟生成完整技术文档从API设计到开发者指南

背景

一位技术工程师需要在30分钟内为一个新上线的REST API编写完整的技术文档。API是一个用户管理服务，包含用户注册、登录、信息查询、信息更新和删除5个接口。文档需要面向第三方开发者，包含快速开始、API参考、SDK使用、错误码和FAQ。团队只有1位工程师，需要用AI提示词流水线完成全链路。

第一步：API设计文档

提示词

你是一位API设计专家。请根据以下信息生成完整的API设计文档：

## API信息
- 服务名称：用户管理服务（User Management API）
- 版本：v1.0
- 基础URL：https://api.example.com/v1/users
- 认证方式：Bearer Token（JWT）
- 数据格式：JSON

## 接口列表
1. POST /users - 用户注册
2. POST /users/login - 用户登录
3. GET /users/{id} - 查询用户信息
4. PUT /users/{id} - 更新用户信息
5. DELETE /users/{id} - 删除用户

## 输出要求
每个接口包含：
1. 接口描述（1-2句话）
2. 请求方法与路径
3. 请求头
4. 请求参数（路径参数/查询参数/请求体）含类型、是否必需、说明
5. 响应格式（成功+失败）含状态码、响应体示例
6. 错误码列表
7. 调用示例（curl命令）

## 约束
- 遵循RESTful规范
- 响应统一使用 {"code": 200, "message": "success", "data": {...}} 格式
- 分页参数统一为 page 和 page_size
- 时间格式统一为 ISO 8601
- 敏感字段（密码等）在响应中不返回

产出：5个接口的完整API文档，含请求参数、响应示例和curl命令。

踩坑：首版文档缺少请求体字段的校验规则。追问"为每个请求体字段添加校验规则（如长度、格式、范围）“后补充完整。

第二步：快速开始指南

提示词

你是一位开发者文档专家。请根据以下API信息编写快速开始指南：

## API信息
- 服务名称：用户管理服务
- 基础URL：https://api.example.com/v1
- 认证：先调用注册接口获取API Key，再调用登录获取JWT Token
- 支持语言：Python、JavaScript、Java

## 快速开始指南结构

### 1. 前置准备
- 注册账号获取API Key
- 开发环境要求

### 2. 5分钟快速调用
- 步骤1：注册用户
- 步骤2：登录获取Token
- 步骤3：查询用户信息
- 每步包含：代码示例（Python）+ 预期输出

### 3. 常见问题快速排查
- 认证失败怎么办
- 请求超时怎么办
- 参数格式错误怎么办

## 约束
- 代码示例可以直接复制运行
- 每步说明不超过3句话
- 总长度控制在1000字以内
- 面向首次使用的开发者

产出：约800字的快速开始指南，含3步调用示例和3个常见问题排查。

第三步：SDK使用说明

提示词

你是一位SDK文档工程师。请为用户管理服务生成Python SDK使用说明：

## SDK信息
- 语言：Python 3.8+
- 安装：pip install example-usersdk
- 源码：https://github.com/example/usersdk-python

## SDK功能
- UserClient类：封装所有API调用
- 自动处理认证（Token刷新）
- 自动重试（指数退避）
- 请求/响应日志

## 文档结构

### 1. 安装
```python
pip install example-usersdk

2. 初始化

from example_usersdk import UserClient

client = UserClient(
    api_key="your_api_key",
    base_url="https://api.example.com/v1"
)

3. 基本用法

为以下5个操作各提供完整的代码示例：

1. 用户注册：client.create_user(…)
2. 用户登录：client.login(…)
3. 查询用户：client.get_user(…)
4. 更新用户：client.update_user(…)
5. 删除用户：client.delete_user(…)

4. 高级用法

• 批量操作
• 分页查询
• 错误处理
• 自定义重试策略
• 异步调用

5. 类型定义

列出所有数据模型类及其字段

约束

• 每个代码示例必须可运行
• 参数说明包含类型、默认值和说明
• 错误处理示例覆盖常见异常

**产出**：完整的Python SDK文档，含安装、初始化、5个基本操作和5个高级用法示例。

## 第四步：错误码参考

**提示词**
```plaintext
你是一位API文档专家。请为用户管理服务生成完整的错误码参考文档：

## 已知错误码
{从第一步API文档中提取的错误码}

## 任务
1. 补充可能遗漏的错误码
2. 为每个错误码提供：
   - 错误码
   - HTTP状态码
   - 错误消息
   - 可能原因（2-3条）
   - 解决方案（2-3条）
   - 示例响应

## 错误码分类
- 认证类（401开头）
- 授权类（403开头）
- 请求类（400开头）
- 资源类（404开头）
- 冲突类（409开头）
- 限流类（429开头）
- 服务器类（500开头）

## 输出格式
### {分类名称}

| 错误码 | HTTP状态码 | 错误消息 | 可能原因 | 解决方案 |

#### 示例响应
```json
{
  "code": 40001,
  "message": "Invalid email format",
  "details": "Email must contain @ symbol"
}

约束

• 错误码格式：5位数字（如40001）
• 每个分类至少3个错误码
• 解决方案要具体可操作

**产出**：7个分类共25个错误码的完整参考文档。

## 第五步：FAQ

**提示词**
```plaintext
你是一位技术支持专家。请为用户管理服务生成FAQ文档：

## 服务信息
- 服务名称：用户管理服务
- 目标用户：第三方开发者
- 主要功能：用户注册/登录/查询/更新/删除

## 任务
生成15个最常被问到的问题，分为以下类别：

### 基础问题（5个）
- 认证相关、Token有效期、多环境支持等

### 技术问题（5个）
- 限流策略、并发控制、数据一致性、批量操作等

### 业务问题（3个）
- 数据隐私、GDPR合规、数据导出等

### 故障排查（2个）
- 常见报错排查、性能优化建议

## 每个FAQ包含
1. 问题
2. 简短回答（1-2句话）
3. 详细说明（如需要）
4. 代码示例（如需要）
5. 相关链接（API文档章节）

## 约束
- 问题要真实，基于开发者实际需求
- 回答要准确，与API文档一致
- 避免简单回答"请参考文档"

产出：15个FAQ，覆盖基础、技术、业务和故障排查四个类别。

成果与复盘

总耗时约30分钟，相比传统技术文档撰写2-3天，人效提升约30倍。

可复用清单

将以上提示词存为技术文档模板，变量化：

• {服务名称}
• {基础URL}
• {接口列表}
• {认证方式}
• {支持语言}

下次新API文档直接套用，预计可压缩到20分钟内完成全套初稿。

核心经验

1. API文档先行：先完成API设计文档，后续文档都基于它生成
2. 代码示例要可运行：AI生成的代码需要实际测试验证
3. 错误码要穷举：让AI按分类补全，不要只列已知的
4. FAQ要真实：基于开发者实际提问，不要编造问题
5. 格式要统一：最后统一检查命名规范、格式和交叉引用

来源：基于技术文档撰写实战流程整理