API 文档蓝图

为 REST 接口生成规范文档蓝图：鉴权、参数表、请求响应示例、错误码表与 OpenAPI 片段

自由如风最新版本 0.1.0更新于 2026-11-02下载 0 次

SKILL.md

1	---
2	name: api-doc-blueprint
3	description: 为 REST 接口生成规范文档蓝图：鉴权、参数表、请求响应示例、错误码表与 OpenAPI 片段，对接前端与第三方时一次说清。
4	---
5
6	# API 文档蓝图
7
8	> 为 REST 接口生成规范文档。纯指令技能：不带脚本、不联网、默认不写任何文件（用户明确要求落盘时除外），产出为可直接使用的文档文本。
9
10	## 文档结构（按序）
11
12	1. 概述：这个接口解决什么问题，谁调用它；
13	2. 鉴权：方式（如 Bearer token）、获取方式、过期与刷新；
14	3. 端点：方法 + 路径 + 幂等性说明；
15	4. 参数表：
16
17	\| 名称 \| 位置(query/path/body) \| 类型 \| 必填 \| 示例 \| 说明 \|
18
19	枚举值列出全部取值与含义；
20	5. 请求示例与响应示例：真实感 JSON（字段值贴合业务，不写 foo/bar），响应附字段说明；
21	6. 错误码表：
22
23	\| 错误码 \| HTTP 状态 \| 含义 \| 调用方处理建议 \|
24	7. 限流与配额：阈值、超限行为、重试建议；
25	8. 变更记录：日期 + 版本 + 变更内容。
26
27	## 写法规则
28
29	- 参数表必须与示例一一对应：示例里出现的每个字段都能在表里找到，反之亦然；
30	- 错误码表覆盖该接口所有可能的失败分支，包括鉴权失败、参数错误、资源不存在、限流；
31	- 时间字段写明时区与格式（如 ISO 8601，UTC）；金额写明单位与精度；
32	- 分页写清：游标还是页码、默认值、上限、排序是否稳定。
33
34	## OpenAPI 3.1 片段
35
36	用户需要时附 OpenAPI 片段：paths、parameters、requestBody、responses 与 components.schemas；schema 用 $ref 复用，不在多处重复定义。
37
38	## 缺失项清单（输出前自检）
39
40	鉴权方式、错误码表、字段单位与时区、分页上限、幂等性——缺任何一项，在文档末尾列出「待补充」并逐项说明为什么需要，不得静默省略。

文件内容是平台检查时读出的文本，只供查看。平台不会运行包里的任何脚本或程序。