api-docs-writer

API 文档编写技能

此技能可将原始 API 规范、端点描述或 Postman 集合转换为清晰、面向开发者的文档，并遵循与 OpenAPI 相近的规范。输出可直接用于开发者门户、README 或 Notion/Confluence 页面。

必需输入

根据已有信息编写。如果缺少以下任何信息，仍须生成完整输出：为每项缺失内容填入合理假设，并标注为 (假设，需确认)，最后列出这些假设。仅当核心主题本身缺失（没有内容可写）时，才先提出问题。

• API 或端点详情（原始规范、Postman 导出内容或文字说明）
• 身份验证方式（API 密钥 / Bearer 令牌 / OAuth 2.0 / 无）
• 基础 URL
• API 版本（例如 v1、v2.3 或“无版本”——会影响弃用说明和版本标头）
• 速率限制（每个令牌或 IP 每秒/每分钟的请求数，如已知；否则填写“未知”）
• 受众（内部开发者 / 外部合作伙伴 / 公众）
• 输出格式（适用于开发者门户和 README 的 Markdown / 适用于 Confluence 或 Notion 的纯文本——注意：此技能不会生成 OpenAPI YAML）

输出格式

针对每个端点，生成以下内容：

---

[METHOD] /path/to/endpoint

摘要： [用一行说明此端点的功能]

描述： [用 2–4 句话说明何时使用此端点、它会返回什么，以及需要了解的重要行为（分页、速率限制、异步处理等）。]

身份验证： [必需 / 可选 — 方式]

---

请求

标头：

标头	必需	描述
Authorization	是	Bearer <token>
Content-Type	是	application/json

路径参数：

参数	类型	必需	描述
id	string	是	资源的唯一标识符

查询参数：

参数	类型	必需	默认值	描述
limit	integer	否	20	每页最大结果数（1–100）
cursor	string	否	—	上一条响应中的分页游标

请求正文：

{
  "field_name": "value",
  "another_field": 42
}

字段	类型	必需	描述
field_name	string	是	[对该字段功能的简明描述]
another_field	integer	否	[描述。如适用，请包含有效范围或枚举值]

---

响应

成功响应：200 OK

{
  "id": "abc123",
  "status": "active",
  "created_at": "2025-04-01T10:00:00Z"
}

字段	类型	描述
id	string	已创建/检索资源的唯一标识符
status	string	当前状态。枚举值：active、inactive、pending
created_at	ISO 8601 string	创建时间戳（UTC）

---

错误代码

状态代码	错误代码	描述	解决方法
400	INVALID_REQUEST	请求正文格式错误或缺少必填字段	根据上述架构检查请求正文
401	UNAUTHORIZED	缺少身份验证令牌或令牌无效	验证 API 密钥或刷新令牌
404	NOT_FOUND	请求的资源不存在	检查路径参数中的 ID
429	RATE_LIMITED	请求过多	暂停请求，并在 Retry-After 标头指定的时间后重试
500	INTERNAL_ERROR	意外的服务端错误	采用指数退避方式重试；如果问题持续存在，请联系支持团队

---

代码示例

至少使用 2 种适合受众的语言生成示例（默认：cURL + Python）：

cURL：

curl -X POST https://api.example.com/v1/endpoint \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"field_name": "value"}'

Python：

import requests

response = requests.post(
    "https://api.example.com/v1/endpoint",
    headers={"Authorization": "Bearer YOUR_TOKEN"},
    json={"field_name": "value"}
)
data = response.json()

---

深入资料

此技能附带支持文件——如有，请使用：

• references/example-first-docs.md — 示例优先的 API 文档：让文档更易用的规则。生成输出时请应用其中的规则；它包含了校准标准和判断要点，而上文的方法摘要对这些内容做了概括。
• templates/endpoint-entry.md — 可填写的交付物模板，内含质量门槛。用户想自行编写文档，而不是让你生成时，请提供此模板。

评分标准（0–40）

提交前，请为此技能的任何输出评分；32 分及以上才达到交付标准。

维度	0	5	10
参数完整性	列出了字段，但没有类型或必填／可选标记	表格完整，但描述只说明字段是什么，没有说明字段有什么作用；缺少枚举值和范围	每个字段都有类型和约束（枚举值、范围、格式），并通过行为及后果加以描述
错误路径覆盖	只有成功路径，没有错误表	列出了标准的 400/401/404/429/500 行，但没有提供解决建议	覆盖全部标准错误及端点特定代码，并说明开发者应采取的措施，包括不安全重试的情况
示例可运行性	使用伪代码、未定义变量或 “YOUR_ENDPOINT” 占位符	提供了示例，但无法直接复制粘贴运行，或只使用一种语言	至少使用 2 种语言，提供真实的基础 URL 和明显为虚构的占位凭证，粘贴后即可运行
行为坦诚度	未说明异步行为、分页、幂等性和旧版特性	在正文中提到特性，但示例和错误行中没有体现	记录各种注意事项，并附上它们实际产生的请求／响应，包括不便的旧版行为

质量检查

• 每个参数都有文档说明（类型、必填／可选、描述）
• 响应字段均有完整的类型说明
• 列出所有相关错误代码，并提供解决建议
• 错误代码至少涵盖：400（错误请求）、401/403（身份验证）、404（未找到）、429（请求过多）、500（服务器错误）——或明确说明哪些代码不适用于此端点
• 代码示例使用实际的基础 URL 和逼真的占位令牌——不得引用未定义的变量，也不得在代码片段外使用 “YOUR_ENDPOINT”
• 在开头清楚说明身份验证方式
• 适用时列出枚举值
• 如果是列表端点，需说明分页方式

反模式

• 不要只记录成功路径——每个端点都必须列出至少 400、401/403、404、429 和 500 的错误代码
• 不要在代码示例中使用 “YOUR_ENDPOINT” 或 “INSERT_TOKEN” 等占位值——请使用与实际基础 URL 相关且看起来真实的占位值
• 对于具有固定可接受值的字段，不要省略枚举值——未记录的枚举值会导致集成错误
• 列表端点不要省略分页说明——开发者若忽略此项，构建的集成会无声无息地漏掉数据
• 不要只描述字段“是什么”，还要说明字段“有什么作用”——“ID”不是文档；“用于检索或更新此资源的唯一标识符”才是

使用示例

• “为此 API 端点编写文档：[粘贴规范或说明]”
• “将此 Postman 集合整理成开发者文档”
• “为 [端点] 编写 API 参考文档”
• “为我们的 [产品] API 编写开发者指南”

示例触发语句

• “为 API 端点编写文档。”
• “编写 API 参考文档。”
• “创建开发者指南。”
• “将原始规范／Postman 集合整理成文档。”