有过"考古式开发"的经历吗？
你接手了一个离职同事留下的老项目，或者在一个庞大的微服务群里找到了一个看似完美契合需求的内部接口。你满怀期待地点击文档链接，结果页面上只有冷冷清清的一行字：TODO: 待补充。
你只能咬着牙去翻源码。从 Controller 顺藤摸瓜到 Service，再到深埋在 DTO 里的参数定义。你试着传了userId，报错400 Bad Request；改传user_id，依然报错。最后你通过断点调试才发现，这个参数需要嵌套在header对象里，而且必须是Long类型。
那一刻，哪怕在这个接口内部运用了最精妙的设计模式，优化到了极致的性能，在你眼里，它依然体验极差。
在软件工程中，代码是写给机器执行的，而文档是写给人类理解的。在微服务和前后端分离盛行的今天，API 文档本质上就是开发者的 UI。
📉 为什么我们总是写不好文档？
我们都知道文档重要，但写文档确实是一件高摩擦的事：
- 语境切换成本高：写代码是逻辑思维，写文档是产品思维。从实现细节跳出来去描述业务价值，需要极大的脑力切换。
- 维护是场噩梦：代码改了一行逻辑，文档没同步，过大半年这文档就成了误导人的"诈骗指南"。
- 缺乏标准化：张三用 Word，李四用 Wiki，王五直接把 JSON 贴在微信群里。
结果就是：所有的“以后补上”，最后都变成了“永不补上”。
🔧 AI：你的“文档翻译官”
如果强迫开发者去当“技术作家”，确实强人所难。但如果我们换个角度：让 AI 来做那个“翻译”呢？
现在的 AI 模型（尤其是国产大模型如 DeepSeek、通义千问等）非常擅长一种转化：从“实现细节”到“使用说明”的转化。你只需要把那段枯燥的代码定义扔给它，它就能自动提取出参数、类型、约束，并生成人类可读的说明。
但这还不够。为了输出一份真正“专业级”的文档，我设计了一套「API 文档生成指令」。它不仅仅是格式化工具，更像是一个严格的文档质检员。
📋 复制这个指令，让接口文档标准化
这套指令内置了 RESTful 规范、OpenAPI 标准以及对开发者体验（DX）的深度理解。它会强制输出包含cURL 示例、错误码说明和多语言调用代码的完整文档。
# 角色定义 你是一位资深的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或技术文档系统中使用。⚡️ 为什么这个指令能提升“开发者体验”？
当你把一个简单的登录接口定义扔给它，它不仅会生成参数列表，更重要的是它会补全那些被你忽略的“最后一公里”体验：
开箱即用的 cURL：
以前对接接口，我得自己拼凑请求地址、Header 和 Body。现在文档里直接给了curl命令，开发者复制并在终端一贴，回车就能看到结果。这种“通了”的瞬间满足感，是 API 体验的关键。消除“猜谜”的 JSON 示例：
很多文档只写了字段名，没写结构。比如user到底是一个 ID 字符串，还是一个包含详细信息的对象？这个指令强制 AI 生成完整的 JSON 响应示例，所见即所得。多语言的“复制粘贴”：
对于使用 Python 或 Node.js 的调用方，直接提供requests或fetch的代码片段。这意味着他们不需要去查 HTTP 库的文档，直接拿来改改就能用。
💡 别让文档成为你的短板
我们常说“代码即文档”（Code as Documentation），但这往往是偷懒的借口。真实的情况是，没有文档的代码，就像没有路标的迷宫。
即使是在内部团队，一份清晰、规范的 API 文档也能极大地降低沟通成本。试想一下，当你的前端同事不再因为少传了一个参数而跑来拍你肩膀，当测试同学能直接根据文档生成用例，你的时间将真正回归到核心业务逻辑的开发上。
把这个 Prompt 加入你的收藏夹。下次写完接口，花 30 秒生成一份文档。这不仅是对使用者的尊重，更是对自己代码质量的一份自信。
