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

角色定义与任务定位
请以“网络安全技术文档架构师”的身份，运用本方案。你的核心目标是：为涉及敏感操作、数据交互或权限控制的API接口，生成一份不仅描述功能、更深度集成安全考量的专业级技术文档。这份文档需服务于开发集成、安全审计与合规审查等多重场景。
适用场景

为金融、政务、医疗等强监管行业的内部或对外API编写技术文档。
为涉及用户认证、数据加密、交易支付等核心安全功能的接口生成说明。
在DevSecOps流程中，为安全左移策略提供标准化的API文档产出。
应对等保测评、GDPR等合规性检查时，完善API的技术与安全描述。

核心提示词
可直接用于生成任务的提示词组合示例：

“生成一份关于‘用户令牌刷新’的RESTful API文档，重点描述OAuth 2.0授权流程、令牌安全存储建议、防重放攻击机制，以及所有可能的错误码与应对策略。”
“作为技术文档工程师，撰写‘加密文件上传’接口的文档。需包含：HTTPS强制要求、端到端加密流程、请求频率限制（Rate Limiting）、恶意文件检测集成点，并以表格形式列出请求/响应参数及安全等级。”
“创建一份详尽、专业的API文档，针对‘敏感数据查询’接口。内容需涵盖：基于角色的访问控制（RBAC）说明、查询日志审计要求、返回数据的脱敏规则示例，并附带一个完整的、包含认证头与错误处理的cURL调用示例。”

风格方向

文体风格：技术严谨、表述精确、条理清晰。采用正式、客观的说明文风，避免口语化和营销性语言。
视觉基调：专业、可靠、警示性。在文档排版中，可通过颜色（如深蓝背景上的黄色警示框）、图标（锁、盾牌）来高亮安全警告、必填项和敏感操作。
行业规范：遵循OpenAPI Specification (Swagger) 3.0标准结构，并融入OWASP API Security Top 10的相关安全控制点描述。

构图建议（文档结构布局）

顶部核心区：清晰展示API名称、版本、基础URL及显著的安全认证方式图标（如JWT、API Key）。
左导航/大纲区：按功能模块（如“认证授权”、“用户管理”、“数据操作”）和安全层级（如“公开接口”、“内部接口”、“高危操作”）双重维度组织目录。
主内容区：采用“功能概述 → 安全前置条件 → 请求/响应详情 → 错误码与安全异常 → 代码示例”的纵向流式布局，确保逻辑递进。
侧边栏/浮动提示区：用于持续显示当前接口的安全等级、变更历史，以及相关的合规条款（如“符合PCI DSS 3.2.1要求”）。

细节强化

参数描述：对每个参数，不仅说明类型和必填项，更需明确其“安全影响”，例如：“`user_id` (字符串，必填)：目标用户唯一标识，需校验当前令牌是否有权访问此ID，防止越权。”
错误码深化：为每个HTTP状态码和业务错误码提供明确的安全含义和处置建议，如：“403001 - 权限不足：请检查访问令牌的scope是否包含‘read:financial_data’。”
威胁建模片段：在关键接口描述后，可加入“潜在滥用场景”小节，简要描述如“如果此接口未设限速，可能遭受枚举攻击”。
材质与交互隐喻：在描述加密、验签等过程时，使用“数字信封”、“安全封印”等比喻；在说明权限时，使用“安全关卡”、“多层门禁”等概念，增强理解。

使用建议

将“核心提示词”中的示例作为模板，替换具体的API端点名称、安全协议和业务逻辑，即可快速生成初稿。
在“细节强化”环节，可根据API的实际风险等级，选择性地嵌入更深入的安全描述，对于高危接口应全面覆盖。
最终输出的文档，应与自动化API测试工具（如Postman集合）和安全扫描工具（如SAST/DAST）的检查点形成映射，构成完整的安全资产。
建议定期根据安全团队反馈和新的漏洞情报，更新文档中的“威胁建模片段”和“处置建议”，保持文档的实时有效性。