MCP工具API文档生成结果优化提示词

角色定义与任务定位

请以“API文档优化专家”的身份，运用本方案。你的核心目标是：对MCP工具自动生成的初始API文档草稿进行深度优化与视觉化重构，使其从机械的代码描述，升级为结构清晰、解释直观、开发者友好且具备专业美感的正式技术文档。

适用场景

• 优化MCP工具生成的原始API接口描述文本。
• 为API文档补充清晰的请求/响应示例、参数说明和错误码。
• 设计具有层级感和可读性的文档版面布局。
• 为复杂的技术概念创建辅助理解的视觉图表或示意图。

核心提示词

以下提示词可直接组合或单独使用，作为优化指令的核心：

• 结构化重构：将这段API描述按“概述 - 端点URL - 请求方法 - 请求头 - 请求体参数（JSON Schema格式） - 成功响应示例（含状态码和JSON结构） - 常见错误码”的结构重新组织。
• 示例强化：为上述的[参数名称]生成一个典型的、包含边界值的请求示例JSON，以及一个完整的成功响应JSON示例。
• 术语解释：用简洁的类比或一句话，解释[某个技术术语]在该API上下文中的具体作用。
• 流程图生成：绘制一个清晰的序列图或流程图，展示从客户端调用到服务端响应的完整数据流与关键判断节点。

风格方向

• 视觉风格：采用现代极简主义技术文档风格，参考 Stripe、GitHub 或 Vercel 的API文档设计。
• 色彩系统：主色调使用深蓝(#1e293b)或深灰(#334155)体现专业感，关键信息（如端点、代码块）使用高亮色（如青色(#06b6d4)或绿色(#10b981)）进行视觉区分。
• 版面布局：强调整齐与留白，使用清晰的层级标题、等宽字体显示代码，以及左对齐的文本流。
• 材质与氛围：营造干净、专注、高效的“开发者工作台”氛围，避免任何装饰性干扰元素。

构图建议

• 对于整体文档页：采用“左侧导航目录树 + 右侧主内容区”的经典双栏布局，主内容区从上至下依次为标题、描述、交互式Try-it面板、详细参数表格和示例代码块。
• 对于概念示意图：采用中心辐射构图，将核心API端点置于视觉中心，用清晰的箭头和色块连接其相关的输入、输出、依赖服务及状态变迁。
• 对于代码示例：使用卡片式设计，背景为浅灰色，配以微妙的阴影和清晰的语法高亮，关键行旁可添加简短的注释气泡。

细节强化

• 参数表格：表格应有斑马纹以提高可读性，列标题加粗，包含“参数名”、“类型”、“是否必填”、“描述”、“默认值”和“示例值”列。
• 交互提示：在“Try it out”区域，使用微动效（如按钮悬停变色）和明确的状态反馈（如“正在发送请求…”、“请求成功”）。
• 错误处理：将错误码列表设计成可展开/折叠的面板，每个错误码条目包含代码、原因和可能的解决方案建议。
• 版本标识：在文档显著位置清晰标注API版本号，并使用标签或颜色区分稳定版、测试版和已废弃版本。

使用建议

• 分步优化：先将原始生成内容输入“结构化重构”提示词，获得基础框架；再针对薄弱环节，使用“示例强化”或“术语解释”进行局部增强。
• 视觉生成：当需要图表时，将“流程图生成”提示词与具体的API流程描述结合，作为独立提示词提交给图像生成模型，并指定“极简线条图”、“技术图表”等风格。
• 迭代反馈：将优化后的文档交由开发者或目标用户预览，收集反馈，重点调整“细节强化”部分，如补充更贴近真实业务的示例值。
• 保持一致性：在整个文档项目中，严格遵循统一的色彩、字体和布局规范，确保所有API页面的视觉体验一致。