网络安全API文档生成高阶版提示词

角色定义与任务定位

请以“网络安全技术文档架构师”的身份，并兼顾“安全合规审核员”的视角来使用本提示词。您的核心目标是：生成一份不仅描述API功能，更深度集成安全设计、威胁模型、合规要点及防护建议的专业级API文档，使其成为开发人员和安全团队均可信赖的集成与审计依据。

适用场景

• 为内部或对外发布的、涉及敏感数据操作或关键业务的Web API/微服务编写正式文档。
• 在DevSecOps流程中，自动化或半自动化生成包含安全章节的API参考。
• 准备用于安全合规性审计（如等保、GDPR）的API接口技术说明材料。
• 对现有API文档进行安全增强与重构，补充威胁缓解措施。

核心提示词

可直接复制并填充具体API信息使用的提示词结构：

• 生成[API名称]的完整RESTful API文档，需包含概述、认证授权、端点列表、请求/响应示例、错误代码。
• 重点突出其安全设计：详细说明采用的认证机制（如OAuth 2.0、API Key）、授权模型（RBAC）、数据加密方式（TLS 1.3、字段级加密）、输入验证与输出过滤策略。
• 集成威胁分析：针对[登录]、[支付]、[数据导出]等关键操作，分析潜在威胁（如注入、越权、信息泄露）并写明对应的缓解措施。
• 补充合规性章节：明确本API在处理[个人身份信息PII]、[支付卡数据PCI]时应遵循的合规要求及配置建议。
• 提供安全最佳实践示例代码（如使用SDK时的安全初始化、错误处理）和监控/审计日志要点。

风格方向

• 文体风格：技术严谨、表述精确、条理清晰。采用正式但不过于学术化的技术文档语言。
• 视觉结构：层级分明，利用清晰的标题（H1-H3）、表格、代码块和列表来组织内容。安全警告、注意事项使用突出标识（如Note、Warning框）。
• 内容色调：专业、可靠、具有警示性。安全相关部分需体现风险意识和防御性设计思想。

构图建议（信息组织框架）

• 顶层框架：1. API概述（功能、版本、基础URL）→ 2. 安全总览（核心安全特性一览表）→ 3. 认证与授权（流程图+步骤详解）→ 4. 资源端点（每个端点独立章节）→ 5. 错误处理（含安全相关错误码）→ 6. 合规与审计 → 7. 附录（SDK安全使用、常见QA）。
• 端点章节结构：端点描述 → HTTP方法/URL → 请求参数（含安全校验规则） → 请求示例 → 响应示例 → 该端点特有安全考量。
• 安全信息植入：将安全要点作为“子模块”嵌入每个相关部分，而非孤立成章。

细节强化

• 术语精确：准确使用“认证”、“授权”、“鉴权”、“混淆”、“哈希”、“签名”等术语，避免混用。
• 示例具体化：请求/响应示例应包含真实的HTTP头（如Authorization头格式）、包含边界值和异常值的参数示例。
• 风险可视化：对复杂的安全交互流程，建议用文字描述辅以简单的序列图或状态转换图说明。
• 版本与变更：明确文档版本，并对安全相关的接口变更（如认证方式升级）设立独立的变更日志和安全升级指南。

使用建议

• 在使用大语言模型生成初稿时，请将“核心提示词”部分作为系统指令或主要提示，并分步骤细化。
• 务必提供真实的API规范（如OpenAPI/Swagger文件）或详细的功能描述作为输入，模型才能生成准确内容。
• 生成后，重点人工复核安全逻辑的准确性、合规条款的适用性以及示例代码的安全性，此部分不宜完全依赖自动化。
• 可将输出结果直接导入Markdown编辑器、Confluence或类似文档平台，其结构已适配标准渲染。
• 定期使用本提示词框架重新生成或更新文档，以保持安全策略与API实际版本同步。