高质量后端接口产品说明文档提示词

角色定义与任务定位

请以“技术产品经理”或“资深后端架构师”的身份，并联合“技术文档工程师”的视角，共同完成以下核心任务：系统性地规划与撰写一份面向开发者、测试人员及合作方的后端接口产品说明文档。你的核心目标是产出一份逻辑严谨、描述精准、示例完备的文档，确保接口功能被清晰定义、调用方式被准确传达，从而提升开发效率、降低对接成本并保障系统稳定性。

适用场景

• 新产品或新功能模块的接口文档首次撰写。
• 现有接口文档的版本迭代与内容更新。
• 为开源项目或API平台提供标准化接口说明。
• 在团队内部建立统一、规范的接口文档书写标准。
• 面向第三方合作伙伴提供技术集成指南。

核心提示词

以下提示词组合可直接或稍作修改后用于文档生成工具或AI辅助写作，以锁定专业内容方向：

• 撰写一份关于 [具体接口名称，如：用户信息查询接口] 的RESTful API产品说明文档。
• 文档需包含：接口概述、版本历史、请求URL、HTTP方法、请求参数说明（必填/选填、类型、示例、描述）、请求头要求、请求体示例（JSON格式）。
• 文档需包含：成功响应结构（状态码、数据字段说明、示例）、错误响应码列表及含义、业务逻辑说明、安全认证方式（如：API Key, OAuth 2.0）。
• 提供完整的调用示例，涵盖多种编程语言（如：cURL, Python, Java, JavaScript）。
• 补充速率限制、数据格式约定、常见问题与解决方案等章节。

风格方向

• 专业严谨：采用技术文档的客观、准确、无歧义的书面语，避免口语化和主观评价。
• 结构清晰：遵循“总-分”结构，模块化组织内容，大量使用分级标题、编号列表和表格进行信息归类。
• 用户友好：在保持专业性的同时，通过示例、注释和流程图（在提示词中描述）来降低理解门槛。
• 视觉统一：提示词中应指定代码块高亮风格、表格样式，确保生成内容在视觉上整齐划一。

构图建议（信息架构）

此处“构图”指文档的信息组织框架，建议采用以下分层结构进行提示：

• 顶层封面区：产品/项目名称、接口文档标题、版本号、最后更新日期、作者/团队。
• 导航区：生成清晰的目录（TOC），包含所有主要章节和子章节的锚点链接。
• 核心内容区：按“1. 概述 -> 2. 接口详情 -> 3. 数据模型 -> 4. 示例 -> 5. 附录”的逻辑流展开。
• 辅助信息区：将“版本历史”、“错误码表”、“常见问题”等作为附录或独立章节置于文档后部，避免打断主流程。

细节强化

• 参数描述：提示时要求对每个参数提供“字段名、类型、是否必填、默认值、取值范围、描述、示例”七要素。
• 示例代码：强调示例的真实性与可运行性，提示需包含完整的导入语句、认证步骤和错误处理片段。
• 状态码故事：不仅列出HTTP状态码，更需描述不同业务场景下（如：查询无结果、参数校验失败、并发冲突）返回的具体业务状态码和用户提示信息。
• 变更突出：在版本更新提示中，明确要求使用“新增”、“变更”、“废弃”、“修复”等标签高亮改动点。
• 术语一致：在提示词中预先定义关键术语（如“会话”、“资产”），并要求全文统一使用。

使用建议

• 将上述“核心提示词”作为与AI对话的初始指令或大纲，然后分章节进行细化补充和迭代生成。
• 在提示中明确指定输出格式，如：“请以Markdown格式输出，二级标题使用##，代码块使用```包裹”。
• 生成初稿后，可进一步使用提示词进行“查漏补缺”，例如：“请检查并补充上述接口文档中关于数据加密传输的说明”。
• 对于复杂逻辑，使用提示词描述需要绘制的图表，如：“请用文字描述一个序列图，说明用户认证成功后调用本接口的完整时序”。
• 本方案为通用框架，实际使用时请将方括号[]中的占位符替换为具体的产品、接口和业务信息。