数据库管理API文档生成高阶版提示词

角色定义与任务定位
以技术文档架构师与API规范专家的身份，为数据库管理系统的API文档生成任务制定提示词方案。目标：生成具备企业级专业度、严格遵循RESTful/GraphQL设计规范、包含认证/分页/错误处理等高级细节的API文档结构化内容。这套提示词应被用于指导AI或人工写作者，产出可直接发布于开发者门户或集成到API管理平台的最终文档。

适用场景

数据库管理平台的RESTful API文档编写（如增删改查、数据表管理、索引操作）
需要统一规范的高阶文档生成（含版本控制、速率限制、安全认证、批量操作）
基于OpenAPI/Swagger规范自动生成后的人工优化或补充
技术博客、内部手册或面向外部开发者生态的API参考文档


核心提示词（可直接复制使用）

全局身份设定：“你是一位精通数据库管理API的技术文档专家，熟悉OpenAPI 3.0规范、RESTful设计原则及数据库底层操作术语。请为以下数据库管理接口生成一份高阶版API文档，每个端点需包含：功能描述、请求方法、URL路径、必选/可选参数（含类型、默认值、说明）、请求体示例（JSON）、成功响应示例、错误状态码及含义、认证方式、限流策略。”
结构模板：“按以下目录结构组织：1. 概述（基础URL、认证方法、公共请求头） 2. 数据模型定义 3. 资源端点列表 4. 每个端点的详细文档（含请求/响应表格、示例代码块） 5. 错误码汇总表 6. 分页与排序规范 7. 变更日志。语言保持技术化、无歧义，禁止使用模糊形容词。”
示例填充：“例如，为 ‘创建数据库表’ 接口生成文档时，请求体必须包含字段：name（字符串，必填）、columns（数组，含name、type、nullable、default等）、engine（枚举：InnoDB/MyISAM，默认InnoDB）。响应返回200及新表ID；400返回字段验证错误详情；409表已存在。”


风格方向

语言风格：中性、规范、专业、无情感渲染。使用行业标准术语（如 resource，endpoint，payload，schema，rate limit）。
视觉风格：代码块采用深色背景，参数表格使用三线表，示例JSON格式化并加语法高亮提示。
一致性：所有端点的描述句式保持一致（“该接口用于…”），请求参数排序按必选/可选分组，响应字段按返回顺序排列。


构图建议

主布局：左侧为端点树形导航（按资源分组），右侧为对应详情区；或采用上下结构：顶部全局概览，下方每个端点独立卡片。
表格设计：参数表列依次为「参数名」-「类型」-「必填」-「默认值」-「说明」；响应表列依次为「状态码」-「含义」-「响应体示例」。
代码区：每个端点示例使用三个标签页切换方式展示：cURL、Python、JavaScript。


细节强化

认证细节：明确说明API密钥或Bearer Token传递方式，是否支持OAuth2.0，以及头部示例：Authorization: Bearer {token}。
分页与过滤：统一使用 ?page=1&size=20&sort=-created_at&filter[name]=user* 格式，并在文档中给出响应头 X-Total-Count 和 Link 的说明。
错误处理：定义标准错误对象结构（如 {code: 40001, message: "字段验证失败", details: [...]}），并提供所有公共错误码的完整对照表。
版本管理：通过URL路径版本（如 /v1/）或请求头版本，说明向后兼容策略。


使用建议

将核心提示词直接粘贴至ChatGPT、Claude或通义千问等模型，指定输出格式为Markdown，便于后续发布。
若需批量生成，可预先定义好每个端点的元数据JSON，让AI据此填充模板。
配合OpenAPI规范工具（如Swagger Editor、Redoc）使用，先由AI生成YAML/JSON规格，再转换为文档页面。
建议为每份文档附加「变更日志」和「版本号」，方便维护；定期更新时只需修改元数据重新生成对应端点内容。