API 文档的 prompt——容错率为零的写作场景
读者会立刻验证你写的对不对
API 文档有一个其他文档类型不具备的特点：读者会立刻用代码验证你写的对不对。
操作指南写得不够清楚，读者可能将就着用、猜着做。但 API 文档不行——参数名大小写错了，请求就 400；类型写错了，序列化就报错；枚举值漏了一个，开发者就卡住了然后去翻源码。
API 文档是所有文档类型中对 prompt 精度要求最高的一种。你的 prompt 如果不够严格，AI 输出的 API 文档就会成为开发者的"踩坑指南"。AI 写 API 文档的三个典型问题
AI 会写 status（String，可选）：筛选状态。就这么一句。开发者看完想骂人："可以传什么值？active？enabled？1？true？不传的话返回什么？"看起来像代码，但跑不通。缺了导入语句、缺了初始化、用了不存在的方法名。开发者复制过去一跑就报错，然后对你的文档失去信任。AI 把错误码扔在文档最后面，像一个可有可无的补充。但开发者在调试阶段最频繁查阅的就是错误码——他的代码在报错，他需要知道这个错误码是什么意思、怎么解决。六个必备模块的 prompt 编码
一个接口的文档，必须包含六个模块。在 prompt 里这样写：
1接口名称与描述：动宾短语命名，1-3 句话说明功能、使用场景和重要限制2请求方法与 URL：明确标注 HTTP 方法和完整 URL，路径参数用花括号标注3参数说明：每个参数包含名称、类型、是否必填、默认值、取值范围、含义4响应体说明：成功响应的完整字段说明，包括嵌套对象5错误码：该接口特有的错误码、HTTP 状态码、含义和常见原因6代码示例：至少提供 cURL 示例，代码必须可直接运行（替换占位符后）参数说明的精度纪律
参数说明是 API 文档中信息密度最高、也最容易出问题的部分。你需要在 prompt 里建立专门的精度纪律：
1. 枚举类型参数必须列出所有合法值，并说明每个值的含义2. 数值类型参数必须说明取值范围（最小值、最大值）3. 有格式要求的参数必须提供格式说明和示例值4. 参数之间存在依赖关系时必须说明5. 可选参数必须说明默认值和不传时的行为来看效果对比：
page_size（Integer，可选）：每页数量。page_size（Integer，可选，默认 20）：每页返回的记录数，取值范围 1 到 100。超过 100 时返回 400 错误。代码示例的三条铁律
示例必须是可直接运行的完整代码（替换占位符后），不接受"示意性"代码包含运行所需的完整上下文——导入语句、初始化、请求头、请求体使用贴近实际业务场景的示例数据，不使用 foo、bar、test123 等无意义占位符再加一条关于占位符的指令：
代码示例中需要读者替换的内容，使用尖括号加描述性名称标注（如 <your-api-key>），并在代码块后逐一说明每个占位符的含义和获取方式。错误码的优先级提升
AI 默认把错误码当附录处理。你需要在 prompt 里提升它的优先级：
错误码是接口文档的核心组成部分，不是附录。每个接口的错误码说明紧跟在响应体说明之后，包含：错误码、HTTP 状态码、含义、常见原因。除了成功响应示例，还必须提供至少一个错误响应示例。开发者在调试时看到的大多是错误响应。如果你的文档只有成功响应的示例，他在遇到错误时就不知道返回的数据结构长什么样、该怎么解析错误信息。
夜雨聆风
