运维监控API文档生成专业版提示词

角色定义与任务定位
请以“资深运维架构师兼技术文档工程师”的身份，运用本提示词方案。你的核心目标是：为内部或外部的运维监控系统API，生成一份逻辑严谨、描述准确、便于开发者理解与集成的专业级技术文档。你的产出应直接服务于系统对接、故障排查与团队协作。
适用场景

为自研的运维监控平台（如监控告警、日志采集、性能度量系统）编写对外API接口文档。
将复杂的命令行工具或脚本功能，重构为标准的RESTful API文档。
为运维团队内部使用的数据查询、状态变更等接口建立统一的文档规范。
在系统升级或架构迭代后，快速更新并生成新版本的API参考手册。

核心提示词
以下提示词组合可直接用于文档生成工具的指令输入或作为内容大纲：

生成一份关于“[具体API端点，如：/api/v1/metrics/query]”的完整API文档。
文档需包含：清晰的接口功能描述、HTTP方法、请求/响应格式（JSON示例）、必选/可选参数说明、状态码定义、以及可能的错误信息列表。
重点说明该接口在运维监控上下文中的典型用途，例如：“此接口用于查询指定时间范围内主机的CPU使用率百分位数据，常用于容量规划报告生成”。
提供与“[相关API端点]”的关联性说明和调用顺序建议。

风格方向

文体风格：技术手册风格，客观、精确、无歧义。采用主动语态与现在时态，如“接口返回…”，避免“我们可以得到…”等模糊表述。
视觉基调：专业、清晰、具有科技感。可类比于AWS、Azure等云服务商API文档的视觉组织方式，强调信息的层级与可扫描性。
术语规范：严格统一使用“端点”、“负载”、“请求头”、“响应体”、“时间戳”、“度量指标”、“标签”等运维与API领域的标准术语。

构图建议（文档结构组织）

采用“总-分”结构：开篇概述模块功能，再分接口详述。
每个接口文档按固定板块排列：接口标题 > 功能简述 > 请求说明（URL、方法、Headers、Body Schema） > 响应说明（成功响应Schema、错误码表） > 代码示例（cURL、Python等） > 注意事项。
使用对比与列表：将参数说明以表格形式呈现，区分“名称”、“类型”、“必填”、“描述”、“示例值”。
通过流程图或序列图（文字描述）来阐明涉及多个API调用的复杂运维操作流程。

细节强化

参数细节：对关键参数（如`start_time`, `end_time`, `metric_name`）提供详细的约束说明（如时间格式：ISO 8601）、取值范围及对查询性能的影响提示。
示例强化：提供真实可运行的请求与响应示例，包括带认证信息的请求头、典型的查询过滤条件、以及包含真实数据结构的响应体。
错误处理：不仅列出错误码，更要给出每个错误码（如`400 Invalid Query`， `503 Data Source Unavailable`）的具体触发场景、可能原因及建议的排查步骤。
版本管理：明确标注API版本号，并对已废弃的参数或端点给出迁移指引。

使用建议

在使用AI辅助生成文档草稿时，将“核心提示词”部分的具体内容作为主要输入，并明确要求其遵循上述风格与结构。
生成后，务必人工校验技术细节的准确性，特别是数据格式、枚举值和业务逻辑边界条件。
可将“风格方向”和“细节强化”中的要点作为文档质量检查清单，逐项核对。
建议配套生成一个简明的“快速入门”指南，将多个相关API串联，形成一个完整的任务（如“如何通过API获取并可视化服务器集群的今日健康状态”），提升文档的实用性。