API 文档蓝图

API 文档蓝图#

为 REST 接口生成规范文档。纯指令技能：不带脚本、不联网、默认不写任何文件（用户明确要求落盘时除外），产出为可直接使用的文档文本。

文档结构（按序）#

1. 概述：这个接口解决什么问题，谁调用它；

2. 鉴权：方式（如 Bearer token）、获取方式、过期与刷新；

3. 端点：方法 + 路径 + 幂等性说明；

4. 参数表：

   | 名称 | 位置(query/path/body) | 类型 | 必填 | 示例 | 说明 |

   枚举值列出全部取值与含义；

5. 请求示例与响应示例：真实感 JSON（字段值贴合业务，不写 foo/bar），响应附字段说明；

6. 错误码表：

   | 错误码 | HTTP 状态 | 含义 | 调用方处理建议 |

7. 限流与配额：阈值、超限行为、重试建议；

8. 变更记录：日期 + 版本 + 变更内容。

写法规则#

• 参数表必须与示例一一对应：示例里出现的每个字段都能在表里找到，反之亦然；
• 错误码表覆盖该接口所有可能的失败分支，包括鉴权失败、参数错误、资源不存在、限流；
• 时间字段写明时区与格式（如 ISO 8601，UTC）；金额写明单位与精度；
• 分页写清：游标还是页码、默认值、上限、排序是否稳定。

OpenAPI 3.1 片段#

用户需要时附 OpenAPI 片段：paths、parameters、requestBody、responses 与 components.schemas；schema 用 $ref 复用，不在多处重复定义。

缺失项清单（输出前自检）#

鉴权方式、错误码表、字段单位与时区、分页上限、幂等性——缺任何一项，在文档末尾列出「待补充」并逐项说明为什么需要，不得静默省略。