SKILL.md
API 文档蓝图#
为 REST 接口生成规范文档。纯指令技能：不带脚本、不联网、默认不写任何文件（用户明确要求落盘时除外），产出为可直接使用的文档文本。
文档结构（按序）#
-
概述：这个接口解决什么问题，谁调用它；
-
鉴权：方式（如 Bearer token）、获取方式、过期与刷新；
-
端点：方法 + 路径 + 幂等性说明；
-
参数表：
| 名称 | 位置(query/path/body) | 类型 | 必填 | 示例 | 说明 |
枚举值列出全部取值与含义；
-
请求示例与响应示例：真实感 JSON（字段值贴合业务，不写 foo/bar），响应附字段说明；
-
错误码表：
| 错误码 | HTTP 状态 | 含义 | 调用方处理建议 |
-
限流与配额：阈值、超限行为、重试建议；
-
变更记录：日期 + 版本 + 变更内容。
写法规则#
- 参数表必须与示例一一对应：示例里出现的每个字段都能在表里找到，反之亦然；
- 错误码表覆盖该接口所有可能的失败分支，包括鉴权失败、参数错误、资源不存在、限流；
- 时间字段写明时区与格式（如 ISO 8601，UTC）；金额写明单位与精度；
- 分页写清：游标还是页码、默认值、上限、排序是否稳定。
OpenAPI 3.1 片段#
用户需要时附 OpenAPI 片段：paths、parameters、requestBody、responses 与 components.schemas；schema 用 $ref 复用，不在多处重复定义。
缺失项清单（输出前自检）#
鉴权方式、错误码表、字段单位与时区、分页上限、幂等性——缺任何一项，在文档末尾列出「待补充」并逐项说明为什么需要，不得静默省略。
用途与依赖
作者没写，这些是平台读文件后整理的，以文件为准。
使用示例
请求：我们有个下单接口 POST /api/v1/orders，用 Bearer token 鉴权，需要传商品 ID 和数量，返回订单号和创建时间。帮我写一份能直接给前端和合作方看的接口文档。
预期
按固定章节依次输出：先写概述说明该接口解决下单问题、调用方为客户端与第三方；鉴权部分写清 Bearer token 的获取、过期与刷新；端点标注 POST /api/v1/orders 并说明是否幂等；参数表列出 item_id、quantity 等字段的名称、位置、类型、必填、示例与说明，枚举列全取值；给出贴合电商业务的下单请求 JSON 与含 order_no、created_at 的响应 JSON，并逐字段解释，时间写明 ISO 8601 UTC；错误码表覆盖鉴权失败、参数错误、商品不存在、库存不足、限流等分支及调用方处理建议；再补限流与配额、变更记录。若说明里缺少时区或分页上限等信息，文末列出待补充项并逐条说明为什么需要。
- 适用场景
- 为已有 REST 接口补写一份规范完整的接口文档
- 前后端对接前，先把鉴权、参数、示例和错误码一次讲清
- 把接口提供给第三方或合作伙伴时，整理成可交付的文档
- 为接口补充 OpenAPI 3.1 描述片段，用于生成客户端或调试
- 接口文档评审前自检，找出鉴权、错误码、时区单位、分页上限等缺失项
- 统一团队接口文档的章节结构与写法规范
- 输入
- 接口的方法与路径（如 POST /api/v1/orders）
- 接口用途与调用方是谁
- 鉴权方式，以及 token 的获取、过期与刷新规则
- 请求参数：名称、位置、类型、是否必填、取值范围或枚举
- 响应字段及其类型、单位、时区格式
- 已知的错误码、对应 HTTP 状态与含义
- 限流阈值与超限后的行为
- 是否需要附 OpenAPI 3.1 片段
- 输出
- 一份按序组织的完整接口文档文本（概述、鉴权、端点、参数表、示例、错误码表、限流配额、变更记录）
- 与参数表一一对应的请求与响应 JSON 示例及字段说明
- 错误码表：错误码、HTTP 状态、含义、调用方处理建议
- 按需提供的 OpenAPI 3.1 片段（含复用 $ref 的 schema）
- 文末的待补充清单及逐项原因说明
- 运行环境
- 未说明
- 依赖
- 无
