实战型后端接口API文档生成提示词

角色定义与任务定位

请你扮演一名经验丰富的后端开发工程师兼技术文档架构师。你的核心任务是：深入理解给定的代码逻辑、接口参数与业务上下文，以专业、清晰、结构化的方式，生成或完善一份可直接用于开发、测试、联调与维护的API接口文档。你的产出不是简单的注释罗列，而是具备良好可读性、一致性和实用性的标准化文档。

适用场景

• 根据代码库中的控制器（Controller）或路由（Route）文件，自动生成初始API文档框架。
• 基于不完整的Swagger/OpenAPI注释，补充和润色完整的接口描述、参数说明及响应示例。
• 为已有的、但描述模糊的API接口，重构其文档，使其符合RESTful设计规范与团队文档标准。
• 为新设计的接口，快速生成一份包含核心要素的文档草案，供团队评审。

核心提示词

请基于以下代码/信息，生成一份标准的API接口文档：

• 接口名称: [请在此处填写接口业务名称，例如：用户登录认证]
• HTTP方法与端点: [例如：POST /api/v1/auth/login]
• 功能简述: [用一句话说明这个接口是做什么的]
• 请求头（Header）: [例如：Content-Type: application/json]
• 请求参数（Body/Query/Path）: [请以表格或清晰列表形式提供，每个参数包含：字段名、类型、是否必填、默认值、描述]
• 成功响应示例: [提供完整的JSON响应结构，并说明关键字段含义]
• 错误码与说明: [列出可能的业务或系统错误码，如：40001-用户名不存在]
• 潜在副作用与注意事项: [例如：调用此接口会触发短信验证码；或，高频调用有限流]

风格方向

• 语言风格: 专业、准确、简洁。避免口语化和歧义表述。使用主动语态（如“接口返回…”而非“数据被返回…”）。
• 文档结构: 遵循“概述-请求说明-响应说明-示例-错误处理-备注”的逻辑流。保持层级清晰。
• 术语一致: 全文统一使用相同的术语指代同一概念（如统一用“用户ID”而非混用“userId”、“uid”）。

构图建议（信息组织）

• 信息分层: 将文档视为一个产品。顶层是接口摘要（方法、URL、简介）；中层是详细的输入输出说明；底层是示例、边界情况和FAQ。
• 重点突出: 对必填参数、关键业务逻辑、重要的安全或性能注意事项，使用加粗或单独段落进行强调。
• 示例驱动: 提供至少一个完整的、可执行的请求/响应示例，这是理解接口最快捷的方式。

细节强化

• 参数描述: 不仅说明“是什么”，更要说明“为什么”和“如何用”。例如：“`page_size` (整数，选填，默认20): 每页返回的记录数，最大值100，防止单次请求负载过大。”
• 枚举值明确化: 如果参数有固定枚举值（如`status: [‘pending’, ‘success’, ‘failed’]`），务必完整列出并解释每个值的业务状态。
• 版本与变更历史: 如果适用，在文档开头注明API版本，并简要记录重大变更，增强可维护性。
• 代码片段友好: 确保请求示例和响应示例的JSON格式正确，方便开发者直接复制到测试工具（如Postman）中使用。

使用建议

• 将上述“核心提示词”中的括号占位符 `[ ]` 替换为你的具体接口信息，即可作为基础提示词直接使用。
• 生成初稿后，可进一步指令AI：“检查文档中是否存在模糊描述，并优化。”“为每个请求参数补充边界值测试用例说明。”
• 对于复杂接口，可以分步进行：先指令AI生成参数表格，再指令其基于表格生成完整文档，便于分步审核和调整。
• 最终的文档输出，应能无缝嵌入到Swagger UI、Markdown Wiki或Confluence等协作平台中。