AI应用API文档生成结果优化提示词

角色定义与任务定位

请以“API文档架构师”或“开发者体验（DX）优化专家”的身份，运用本提示词方案。您的核心目标是：指导AI工具（如大型语言模型）生成结构严谨、内容完整、符合行业规范且易于开发者理解与使用的高质量API文档，从而提升产品的技术可信度与集成效率。

适用场景

• 为全新的RESTful或GraphQL API接口自动生成初始文档草稿。
• 对现有零散、不规范的API描述进行结构化整理与优化。
• 为SDK、代码库或开发工具包创建配套的集成指南。
• 构建标准化、可复用的API文档生成流程与内容模板。

核心提示词

以下提示词组合可直接复制使用，请根据具体API内容替换“{ }”内的变量。

• 基础生成指令：“作为专业的API文档工程师，请为以下API端点生成详细文档。请严格按照‘概述 - 认证 - 请求参数（必填/选填、类型、说明、示例）- 响应示例（成功/错误）- 状态码 - 使用示例（curl, Python等）’的结构组织内容。API信息如下：[此处粘贴API基本信息]”
• 流程完整性强化：“请生成一个完整的API调用流程文档，必须包含：1. 前置条件（如获取API Key）；2. 分步请求构建说明；3. 完整的请求/响应示例（含Headers）；4. 常见错误排查清单；5. 下一步操作建议（如如何解析响应数据）。”
• 质量优化指令：“请优化以下粗糙的API描述，使其达到生产级文档标准：确保术语准确一致，为每个参数补充默认值和取值范围说明，为响应字段添加详细的数据结构定义，并补充至少两个不同编程语言（如Python和JavaScript）的调用示例。”

风格方向

• 语言风格：采用客观、精准、简洁的技术说明文风，避免营销口吻。使用主动语态（如“发送POST请求”而非“一个POST请求被发送”）。
• 格式规范：遵循OpenAPI Specification (Swagger) 或类似主流规范的逻辑结构，确保层级清晰。
• 视觉基调：在描述中暗示文档应具备的“视觉感”——如“代码块高亮清晰”、“参数表格排列整齐”、“留白适度便于阅读”，为后续的排版设计提供方向。

构图建议（信息架构）

将API文档想象为一个层次分明的信息界面，建议采用以下“构图”：

• 顶层全景：提供清晰的导航目录（侧边栏或顶部栏），展示所有API端点分组。
• 中心聚焦：每个API文档页以“快速开始”或“核心功能示例”作为视觉焦点，让开发者能最快上手。
• 细节面板：使用折叠面板或标签页来组织“请求参数”、“响应体”、“错误码”等细节信息，保持页面清爽。
• 流程引导：通过流程图或序列图，可视化展示认证、调用、响应的完整数据流。

细节强化

• 参数描述：不止于类型，补充“业务含义”、“约束条件”（如正则表达式、枚举值）、“关联参数”说明。
• 错误处理：为每个可能的HTTP状态码提供明确的错误信息（`code`和`message`）及具体的解决建议。
• 代码示例：示例代码应包含必要的错误处理逻辑和注释，并注明所需的依赖库及版本。
• 版本控制：明确标注API版本号，并对不同版本间的变更（如废弃、新增）给出醒目提示。
• 材质与交互感：在提示中可加入“像可交互的沙盒环境一样提供实时测试感”、“关键警告信息使用醒目的色块突出”等描述，引导生成更具实用性的内容。

使用建议

• 分步迭代：首先使用“基础生成指令”产出框架，再使用“质量优化指令”针对薄弱环节进行增强。
• 结合上下文：在提示词中提供少量优秀的API文档范例作为风格参考，能显著提升生成质量。
• 变量具体化：尽可能将`[此处粘贴API基本信息]`替换为真实的接口名称、URL、参数列表，信息越具体，产出越精准。
• 后续人工校验：AI生成后，务必人工校验技术准确性、安全性（如是否误泄露敏感信息）和逻辑连贯性。