为什么我的接口总是打不开，像个神秘的黑盒？

有过"考古式开发"的经历吗？ 你接手了一个离职同事留下的老项目，或者在一个庞大的微服务群里找到了一个看似完美契合需求的内部接口。你满怀期待地点击文档链接，结果页面上只有冷冷清清的一行字：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文档。文档应该能帮助开发者快速上手调用接口，同时包含足够的细节供深入了解。