你的 API 文档是"天书"还是"说明书"？用 AI 重构开发者体验 (DX) 的最后一公里

在 API 经济时代，有一个被长期忽视的关键指标：TTFC (Time to First Call)——开发者从看到文档到成功发起第一次调用的时间。

如果这个时间超过 15 分钟，集成的流失率将飙升至 40%。

然而，现实是残酷的。对于大多数后端工程师而言，写代码是"构建帝国"，而写文档是"打扫战场"——枯燥、低效且毫无成就感。这种心态导致了后端交付的 API 往往是个"黑盒"：参数定义模糊、示例代码缺失、错误码语焉不详。前端和第三方开发者被迫通过微信群截图、口头询问甚至"猜谜"来完成对接。

这不仅仅是沟通效率的问题，这是开发者体验（Developer Experience, DX）的灾难。

InfoQ 的技术观察显示，优秀的 API 文档不应被视为代码的附属品，而应被视为**"独立的产品"**。它是服务对外的唯一界面，直接决定了服务的可用性和价值。

现在的转折点在于：利用生成式 AI，我们不仅能自动化"打扫战场"，更能将文档质量提升到"产品级"的高度。

重新定义文档：从"存量记录"到"服务契约"

传统的文档生成工具（如 Swagger UI）解决了"有无"的问题，但解决不了"好坏"的问题。它们能自动生成参数列表，但无法解释"为什么这样设计"；它们能列出返回值，却提供不了"真实场景的示例"。

API 文档生成指令的设计哲学，是将 AI 转化为一位**"全视角的文档产品经理"**。

它不再是被动地将代码注释转换为 Markdown，而是要求 AI 基于 RESTful 规范和用户视角，主动构建一份完整的"服务契约"。这份契约包含了三个维度的升级：

1. 准确性：严格的类型定义和约束条件。

2. 完整性：覆盖正常响应、异常边界和业务规则。

3. 易用性：提供多语言的可运行（Copy-Pasteable）代码示例。

核心指令代码

这份名为"API 文档专家"的指令，凝聚了许多技术写作的最佳实践。请完整复制以下指令，不要删减任何约束条件，以确保 AI 输出的文档具备企业级的专业水准。

# 角色定义你是一位资深的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或技术文档系统中使用。

DX 进阶：构建文档的"金字塔"体系

拥有了这套指令，我们将不再生产那种"只有上帝和原作者能看懂"的文档。这套体系将文档质量推向了三个进阶层级。

层级一：结构化数据的"精准映射"

最基础的层级是**"讲清楚"**。

很多手写文档的通病是参数描述缺失。比如一个 status 字段，后端认为写个 int 就够了，但前端需要知道 0、1、2 分别代表什么。

在使用指令时，我们可以输入模糊的描述：

"返回数据包含订单状态 status，有待支付、已支付、取消三种。"

AI 会自动将其转化为标准化的表格：

这种**"枚举值的显性化"**，直接消除了前后端联调中最常见的"魔术数字"猜谜游戏。

层级二：场景化的"仿真模拟"

第二个层级是**"能运行"**。

静态文档最大的痛点是"无法 Copy"。开发者需要自己拼凑 URL、Header 和 Body。指令强制要求 AI 输出 cURL 和多语言示例（Python/JS）。

这意味着，前端开发者在阅读文档时，可以直接复制 cURL 命令到终端运行，或者复制 JS 代码到项目中。这种**"Copy-Pasteable"的特性，是提升 TTFC 指标的关键。AI 生成的不仅仅是文本，而是可执行的最小单元**。

层级三：防御式的"错误预演"

最高层级是**"懂避坑"**。

"只有成功路径的文档不是好文档"。很多文档只写了 200 OK 的情况，却对 4xx/5xx 闭口不谈。当报错发生时，调用者一脸茫然。

本指令特别强化了**"错误码说明"**章节。AI 会根据接口特性（如登录接口），自动补全潜在的错误场景：

• 40001: 凭证无效

• 42901: 调用频率超限

• 50000: 内部服务降级

这种防御性的文档设计，为调用者提供了预先的异常处理指引，极大地降低了沟通成本。

不同模型的"文档风格"测评

在实际工程中，不同的国产大模型在执行该指令时展现出了差异化的特质，开发者可根据团队风格按需选择：

1. DeepSeek（深度求索）：它是**"严谨的架构师"**。它生成的 JSON Schema 定义极其严密，对嵌套对象的类型描述最准确，非常适合金融、支付等对字段精度要求极高的核心业务接口。

2. 通义千问（Qwen）：它是**"贴心的布道师"**。在生成"调用示例"时，Qwen 往往会添加详细的注释，甚至提示需要安装哪些依赖包（如 pip install requests），对初级开发者非常友好。

3. 智谱清言（GLM）：它是**"规范的标准化委员"**。GLM 非常擅长处理那些复杂的行业标准术语，生成的文档语气最正式，格式最整齐，非常适合生成对外发布的 OpenAPI 文档。

结语：接口即产品，文档即交互

在微服务和 SaaS 盛行的今天，API 已经成为了软件系统的"原子能力"。

糟糕的文档就像一个没有门把手的房间，里面装修得再豪华，用户也进不去。而优秀的文档，则是一把精密的钥匙，轻轻一转，价值即刻释放。

不要让你的 API 成为一个"沉默的黑盒"。利用 AI 指令，将那些隐性的逻辑显性化，将那些复杂的调用简单化。当你开始像打磨产品一样打磨文档时，你其实是在重塑整个技术团队的协作文化——从"以我为主"转向"用户至上"。

这不仅是文档的胜利，更是工程效能的胜利。