专业版BI报表API文档生成提示词

角色定义与任务定位

请以一名资深技术文档工程师或后端架构师的身份，你的核心目标是：为一套企业级BI（商业智能）报表系统的API接口，生成一份高度结构化、内容精确、风格专业、可供开发人员直接对接使用的正式API文档。你的产出不是简单的接口列表，而是一份体现系统严谨性与专业性的技术规范。

适用场景

• 为内部开发团队或外部合作伙伴提供BI数据服务的API对接文档。
• 将零散的接口说明整合为统一、标准的线上API参考手册。
• 在项目交付、系统升级或开放平台建设中，生成符合RESTful规范的专业文档。

核心提示词

可直接用于文档生成工具或作为内容大纲的核心指令组合：

• 生成一份专业版BI报表数据API文档，遵循OpenAPI 3.0规范。
• 文档需包含：概述（系统简介、认证方式、基础URL）、通用错误码列表。
• 为“获取多维报表数据”、“导出报表为PDF/Excel”、“订阅报表定时推送”三个核心接口，分别编写详细说明。
• 每个接口说明必须包含：端点路径、HTTP方法、请求头、请求参数（必填/选填、类型、示例、描述）、请求体示例（JSON格式）、成功响应示例（JSON格式，包含模拟的报表数据字段）、失败响应示例。
• 所有参数描述需精确，例如：“date_range: string, 格式YYYY-MM-DD~YYYY-MM-DD，表示查询的数据日期范围”。

风格方向

• 语言风格：技术化、客观、精确。使用“必须”、“可选”、“枚举值”、“状态码”等明确术语，避免模糊口语。
• 视觉风格（若生成带排版的文档）：采用经典的技术文档布局，深色/浅色双模式代码高亮，清晰的层级标题（H1, H2, H3），表格呈现参数列表，使用图标区分HTTP方法（GET蓝色，POST绿色等）。
• 整体质感：专业、可靠、去装饰化。重点突出信息的可读性和查找效率，体现企业级工具的信任感。

构图建议

• 信息架构：采用“总-分”结构。顶部全局概述，左侧导航区为接口分类菜单，右侧主内容区按“概述-快速入门-接口详情-附录”顺序展开。
• 内容区块：每个接口详情页应明确分割为“接口描述”、“请求”、“响应”、“示例”四大板块，使用卡片或分隔线区分。
• 焦点引导：通过加粗、不同背景色块（如浅灰色背景放置代码示例）引导用户视线至关键信息，如端点URL和重要参数。

细节强化

• 数据示例真实性：响应示例中的模拟数据应贴近真实业务，如包含“sales_amount: 1254300.50, growth_rate: 0.152, region: ‘华东’”等具象字段。
• 错误场景具体化：不仅列出错误码，更需提供典型场景，如“当查询时间范围超过权限限制时，返回403错误及消息‘超出许可的数据时间窗口’”。
• 版本管理提示：在文档头部注明当前API版本号，并在涉及变更的接口处添加“自v1.2版本新增”或“v1.1版本已弃用”的标识。
• 术语一致性：全文统一使用“维度”、“度量值”、“数据立方体”等BI领域术语，并在附录提供术语表链接。

使用建议

• 将“核心提示词”部分直接输入到如Swagger Editor、Apifox等API文档生成工具，或作为指令发送给AI文档助手，以快速生成文档草稿。
• 根据实际API调整接口名称、参数和示例数据，但务必保持整体结构与专业度。
• 生成后，重点人工核对业务逻辑的准确性、参数约束条件（如枚举值、取值范围）以及示例数据的合理性，这是AI难以完全确保的部分。
• 可结合“风格方向”与“构图建议”，在文档工具中进行主题和布局配置，确保最终呈现效果符合专业版定位。