API文档提示词：一键将Swagger定义转化为开发者级交互文档
提示词描述：
专为技术团队设计的API文档生成提示词。将生硬的Swagger/OpenAPI定义转化为包含业务语境、最佳实践和故障排查SOP的开发者友好文档。有效降低前后端及外部开发者的接入成本，提升API交付质量与沟通效率。
提示语关键词：
API文档生成,AI写技术文档,Swagger转文档,API接口文档模板,开发者文档自动化
提示词内容：
【应用场景】
后端研发团队在交付RESTful API时，常面临OpenAPI/Swagger定义生硬、缺乏业务语境的问题。本提示词旨在将冷冰冰的接口定义转化为具备高可读性、包含最佳实践的开发者友好型文档，降低前后端联调的沟通成本。
【案例描述】
某SaaS平台开放平台团队需对外发布支付网关API。原始Swagger文件仅包含字段类型和必填项，缺乏业务流转说明和错误码排查指南。使用该提示词后，AI自动补充了幂等性设计说明、重试机制建议及具体的cURL调用示例，使开发者接入时间缩短了40%。
【提示词正文】
你是一位拥有10年经验的资深技术布道师和API架构师。请根据我提供的 {API接口JSON或YAML定义}，为 {目标受众级别，如：初级开发者/资深架构师} 编写一份结构化的API接入文档。
要求：
1. 业务语境：用一句话概括该接口的核心业务价值及典型使用场景。
2. 核心逻辑：拆解请求参数的业务含义，指出潜在的边界条件和并发限制。
3. 最佳实践：提供至少2个不同维度的调用示例（如：成功场景、异常降级场景），并附带cURL或代码片段。
4. 故障排查：针对可能出现的4xx/5xx状态码，提供SOP级别的排查步骤。
【使用技巧】
在 {API接口JSON或YAML定义} 中，尽量补充一些注释或枚举值说明。如果接口涉及复杂的状态机流转，建议在提示词中额外附加状态机流转图的文字描述，以便AI生成更精准的逻辑说明。
【延伸用法】
可将此提示词与CI/CD流程集成，通过Webhook在代码合并时自动触发API文档更新，并结合RAG（检索增强生成）技术，接入历史工单库，让AI生成的“故障排查”模块基于真实历史Bug进行动态更新。