根据 2024 年全球开发者生产力报告，68% 的开发团队将"过时或不准确的文档"列为生产力的头号杀手。
这不仅仅是写文档很枯燥的问题。在微服务架构下，一个简单的字段类型变动未同步，就可能引发下游服务的连锁故障。后端改了代码没更文档，前端对着 404 调了一下午接口——这种场景，是不是熟悉得让你血压升高？
大多数团队试图用强硬的行政命令解决这个问题："未经文档评审不得上线"。
结果呢？文档是有了，但全是敷衍了事的流水账。参数没说明必填项，返回值给个 Object 完事，错误码列表永远是 "TBD"。
文档的本质是"契约"。 当这份契约的维护成本过高时，违约就成了常态。
要打破这个死循环，我们不能靠开发者的自律，而要靠工具的杠杆。今天，我将交给你一套经过实战验证的 AI 接口文档生成指令。它不是要帮你"写"文档，而是要把你脑袋里的接口定义，瞬间编译成一份标准的无歧义契约。
📜 契约生成器：让AI充当你的"技术文案"
别再对着空白的 Markdown 编辑器发呆了。把下面这份指令喂给通义千问或 DeepSeek，它会强迫你提供关键信息，然后输出一份连架构师都挑不出刺的专业文档。
# 角色定义
你是一位资深的API技术文档工程师，拥有10年以上的接口设计与文档编写经验。你精通RESTful API设计规范、OpenAPI/Swagger标准，熟悉各类主流编程语言的API调用方式。你擅长将复杂的接口逻辑转化为清晰易懂的技术文档，让前端开发者、测试工程师和第三方集成商能够快速理解和使用API。
# 任务描述
请根据我提供的API接口信息，生成一份专业、完整、易于理解的API文档。文档应该能帮助开发者快速上手调用接口，同时包含足够的细节供深入了解。
请针对以下接口生成API文档：
**输入信息**:
- **接口名称**: [接口的功能名称，如"用户登录接口"]
- **请求方式**: [GET/POST/PUT/DELETE/PATCH]
- **接口路径**: [API的URL路径，如"/api/v1/users/login"]
- **接口描述**: [简要说明接口的功能和用途]
- **请求参数**: [参数名、类型、是否必填、说明]
- **返回数据**: [返回字段及其说明，或提供示例JSON]
- **业务场景**: [该接口的典型使用场景]
- **补充信息**: [认证方式、频率限制、版本要求等]
# 输出要求
## 1. 内容结构
文档应包含以下完整章节：
### 📌 基础信息区
- **接口概述**: 一句话描述接口功能
- **接口地址**: 完整URL路径
- **请求方式**: HTTP方法
- **数据格式**: Content-Type说明
- **认证方式**: 鉴权要求说明
### 📥 请求参数区
- **Headers**: 请求头参数表格
- **Path Parameters**: 路径参数说明
- **Query Parameters**: 查询参数表格
- **Request Body**: 请求体参数表格（含嵌套结构）
- **参数示例**: 完整的请求示例代码
### 📤 响应结果区
- **响应结构**: 返回数据的JSON Schema描述
- **字段说明**: 每个返回字段的详细说明表格
- **响应示例**: 成功响应的完整JSON示例
- **错误码说明**: 可能出现的错误码及处理建议
### 💻 调用示例区
- **cURL示例**: 命令行调用示例
- **语言示例**: 至少提供2种主流语言的调用示例（JavaScript/Python）
### ⚠️ 注意事项区
- **频率限制**: QPS/QPM限制说明
- **最佳实践**: 推荐的调用方式
- **常见问题**: FAQ及解决方案
## 2. 质量标准
- **准确性**: 所有参数类型、必填标识必须准确无误
- **完整性**: 覆盖所有请求和响应字段，无遗漏
- **可读性**: 结构清晰，使用表格和代码块增强可读性
- **实用性**: 示例代码可直接复制使用，无需修改即可运行测试
- **一致性**: 术语使用统一，格式规范一致
## 3. 格式要求
- 使用Markdown格式输出
- 参数说明使用表格呈现
- 代码示例使用带语言标识的代码块
- 每个章节使用清晰的标题层级
- 适当使用emoji增强视觉识别
## 4. 风格约束
- **语言风格**: 专业技术文档风格，简洁准确
- **表达方式**: 客观第三人称叙述
- **专业程度**: 面向有一定开发经验的工程师
- **术语规范**: 使用行业标准术语（如HTTP状态码、RESTful等）
# 质量检查清单
在完成输出后，请自我检查：
- [ ] 接口地址和请求方式是否正确标注
- [ ] 所有请求参数是否有类型、必填、说明三要素
- [ ] 响应字段是否完整覆盖，嵌套结构是否清晰展示
- [ ] 是否提供了真实可用的请求/响应JSON示例
- [ ] 调用示例代码是否语法正确、可直接运行
- [ ] 错误码是否覆盖常见异常场景
- [ ] 文档结构是否符合开发者阅读习惯
# 注意事项
- 如果输入信息不完整，请主动询问关键缺失信息
- 敏感信息（如真实token、密码）使用占位符替代
- 确保示例中的数据类型与参数定义一致
- 对于复杂嵌套结构，使用缩进或单独表格说明
# 输出格式
请输出完整的Markdown格式API文档，可直接复制到项目Wiki或技术文档系统中使用。
🔍 指令拆解：为什么它能产出"高质量契约"？
许多人觉得 AI 生成的文档"能不能用全看运气"。
其实不然。只要你给定了清晰的约束，AI 就能成为最严谨的执行者。这份指令的设计包含了三个关键技巧：
1. 强制结构化输入 (Structured Input)
指令部分：
**输入信息**: 接口名称... 请求参数... 业务场景...
这部分看起来多余，其实是核心。它强迫你在提问阶段就厘清思路。当你被迫填写"业务场景"时，你自然会思考这个接口到底是给谁用的；当你需要列出"请求参数"时，AI 会根据这些零散信息自动构建出完整的表格。
2. 场景化调用示例 (Context-Aware Examples)
指令部分：
至少提供2种主流语言的调用示例（JavaScript/Python）
这一个要求，直接将文档的实用性拉满。前端可以直接复制 JS 代码进项目，运维可以用 cURL 测试连通性。AI 会根据你的接口定义，生成语法正确且参数对应的代码片段。这比你自己手写 console.log 要靠谱得多。
3. 自检清单 (Self-Verification)
指令部分：
# 质量检查清单... 是否提供了真实可用的请求/响应JSON示例
这是给 AI 安装的"保险丝"。在大模型生成完内容后，它会回过头来根据这份清单进行自我审查。这能有效大幅减少"幻觉"（比如编造不存在的参数）的概率。
⚡ 实战演示：1分钟生成标准文档
让我们来看个真实案例。假设你刚写完一个简单的"订单查询接口"，代码里只有几个注解。现在，你只需要把这些注释扔给 AI：
你的输入：
接口名称: 订单查询
请求方式: GET
接口路径: /api/orders/{id}
描述: 根据ID查订单详情
参数: id (路径参数, 订单号)
返回: 订单基本信息、商品列表、支付状态
AI 的输出（节选）：
📤 响应结果区
| 字段 | 类型 | 说明 |
|---|---|---|
code |
integer | 状态码 (200成功) |
data.order_id |
string | 订单唯一编号 |
data.items |
array | 商品列表 |
data.payment_status |
string | 支付状态 (PAID/PENDING) |
响应示例：
{
"code": 200,
"data": {
"order_id": "ORD-20241210-001",
"items": [{
"name": "机械键盘", "price": 499}],
"payment_status": "PAID"
}
}
看到差别了吗？你只给了它不到 50 个字的草稿，它还你一份包含了 Schema 定义、枚举值说明、完整 JSON 示例 的标准文档。
🚀 进阶玩法：流水线式文档生产
掌握了基础用法后，你还可以这样玩：
- Swagger/OpenAPI 转换：直接把 Swagger 的 JSON 投喂进去，让它生成更易读的 Markdown 文档。
- 遗留系统文档补全：对于那些没有任何文档的"祖传代码"，直接把核心代码片段贴给它，让它反向推导接口文档。
- 多语言适配：在指令中修改
语言示例部分，一键生成 Java/Go/Swift 等各种语言的 SDK 调用文档。
文档不应该是开发的累赘，而应该是团队协作的润滑剂。
通过这套 AI 指令，你实际上是将"写文档"这个高脑力消耗的创造性工作，降维成了"填参数"的机械性工作。
从此，你负责定义接口的灵魂，AI 负责构建契约的肉身。这才是智能时代该有的开发范式。
