编程开发 编辑复核
API 文档与示例请求生成
根据真实接口契约写可运行的 API 文档，保留认证、错误、幂等、分页和兼容性说明。
PROMPT WORKBENCH
复制后替换变量
保留结构，先填真实信息，再把结果交给模型运行。
你是一名开发者文档工程师。请只根据实际路由、类型和测试响应生成 API 文档，不凭经验补充不存在的字段或状态。
先区分已知事实、合理假设和待核验信息；没有依据的内容写“待验证”，不要为了完整而猜测。
请按以下结构输出：
1. 说明用途、认证、权限、请求参数和字段语义
2. 提供最小成功、分页、空结果和错误响应样例
3. 列出幂等、限流、重试、排序和版本兼容性
4. 设计文档与接口变更的回归检查
输入变量：
- 接口路由（{{route}}）：提供方法、路径和版本。
- 请求响应类型（{{schema}}）：提供真实类型、枚举和必填字段。
- 认证与权限（{{auth}}）：说明匿名、登录和管理员权限。
- 测试响应（{{tests}}）：提供脱敏的成功和错误响应。
约束：保留用户的真实语气和业务边界；把事实、推断与建议分开；涉及日期、价格、版本、法规或安全的内容写明来源和采集时间。HOW TO USE
使用说明
- 先从代码和测试生成草稿，再让接口负责人确认语义。
- 发布后用契约测试阻止文档和接口再次漂移。
WHEN IT FITS
适用判断
适合这些情况
- 接口已经定型，需要写出可供调用方参考的文档。
- 你能提供实际的请求响应结构或类型定义。
- 需要示例请求，方便调用方直接试。
换个做法更好
- 接口还在改：文档会反复重写，先稳定契约。
- 你要写的是项目 README：用《README 与交接文档草稿》。
- 已有 OpenAPI 定义：直接生成文档比让模型改写更准。
FAILURE MODES
常见翻车与修正
- 示例里的字段名和实际接口对不上。
把真实的类型定义或一次实际请求响应粘进输入，要求示例严格依据它生成。
- 示例中出现真实格式的 token 或用户 ID。
要求所有敏感值用明显的占位符，并检查示例里没有可以直接用的凭据或真实用户数据。
- 只写了成功响应，错误情况没有文档。
补充要求：列出所有错误码、触发条件和调用方应该怎么处理，包括限流和鉴权失败。
ACCEPTANCE
怎么判断输出合格
- 字段名、类型和实际接口一致。
- 示例中没有真实凭据或用户数据。
- 错误码、触发条件和处理建议都有文档。
- 示例请求可以直接复制修改后使用。
SAFETY BOUNDARY
使用边界
- 示例请求里的 token、真实用户 ID 和内网域名要替换成占位符。
- 参数说明和返回结构必须对照实际代码核对，文档与实现不符会直接导致集成方出错。