开源模型API文档生成结构化提示词

角色定义与任务定位

请以“开源项目技术文档架构师”的身份，运用你的技术理解与结构化写作能力，将散乱的技术接口信息，转化为逻辑清晰、格式规范、便于开发者直接使用的API文档。你的核心目标是生成可直接集成到项目中的高质量文档内容。

适用场景

• 为GitHub、Gitee等平台上的开源项目自动生成或补全API文档。
• 将代码注释或接口定义快速转换为标准化的说明文档。
• 统一团队内部或跨项目间的API文档风格与结构。
• 为模型服务、SDK或工具库创建用户友好的接口使用指南。

核心提示词

可直接复制使用的提示词组合示例：

• “作为项目技术文档工程师，请为以下[编程语言，如Python]函数生成完整的API文档。需包含：函数签名、功能描述、参数详解（名称、类型、是否必需、说明）、返回值类型与说明、可能抛出的异常、以及一个简洁的代码调用示例。”
• “你是一位专注于RESTful API设计的文档专家。请根据提供的接口路径和JSON数据示例，生成包含以下章节的文档：接口概述、HTTP方法、请求URL、请求头、请求参数（路径/查询/体）、请求体示例、成功响应（状态码、数据结构）、错误响应、以及一个使用curl命令的调用演示。”
• “请以清晰、无歧义的技术文档风格，结构化地描述这个[类/模块]的API。内容需包括：类概述、属性列表（名称、类型、描述）、方法列表（方法名、签名、功能简述），并重点为每个公共方法展开详细说明。”

风格方向

• 语言风格：客观、精准、简洁。使用现在时态，主动语态。避免主观评价和营销性语言。
• 文档气质：专业、严谨、开发者友好。类似于ReadTheDocs、Swagger UI或主流科技公司官方文档的质感。
• 视觉联想：干净的代码高亮区块、清晰的层级标题、规整的表格参数说明、适度的留白与分隔线。

构图建议（信息结构）

• 顶部总览：放置API名称、简短有力的功能概述、版本信息及快速导航锚点。
• 主体结构：采用“概述 -> 快速开始（示例） -> 详细参数说明 -> 返回值/响应体详解 -> 错误处理 -> 更多示例/注意事项”的经典流线。
• 信息分层：使用标题（H1, H2, H3）建立清晰的文档骨架。关键信息（如默认值、必填项）使用加粗或高亮。
• 代码区块：为所有示例代码提供语法高亮，并确保代码可独立运行或清晰展示调用关系。

细节强化

• 参数表格：为参数列表设计表格，包含字段名、类型、是否必需、默认值、描述、枚举值（如有）等列。
• 术语一致：全文保持对同一技术概念命名的一致性，并在首次出现时提供简短解释或链接。
• 前后对照：在请求示例和响应示例中，使用相同的字段名，并确保与参数描述一一对应。
• 错误枚举：不仅列出错误码，更应说明触发条件及可能的解决建议。
• 扩展链接：在文档末尾或相关部分，提供指向源码位置、相关API、更高级教程的链接。

使用建议

• 将“核心提示词”中的示例作为模板，替换方括号[]内的具体内容（如编程语言、函数名、接口路径）后直接使用。
• 生成文档后，建议人工复核技术细节的准确性和示例代码的正确性。
• 可根据项目需求，在提示词中追加特定要求，如“遵循OpenAPI 3.0规范”、“生成Markdown格式”、“包含身份认证说明”等。
• 此方案生成的文档内容，可直接粘贴至项目的docs文件夹、Wiki页面或集成到CI/CD流程中自动更新。