api-documenter

api-documenter 技能概览

api-documenter 能做什么

api-documenter skill 用来帮助 agent 创建和完善 API 文档，产出形式是 OpenAPI/Swagger 规范；同时也提供了适用于 REST 风格 API 结构的辅助材料，并对 GraphQL 做了较轻量的提及。实际使用中，它最有价值的场景是：你需要更快拿到一个可用的 openapi.yaml，而不是从空白文件起步，或只靠一个泛泛的“写 API 文档”提示词。

谁适合使用 api-documenter

最适合的使用者包括开发者、技术写作者、DX 团队和平台工程师——尤其是那些需要用标准、机器可读的格式去描述 endpoints、请求/响应结构、认证方式和错误处理的人。若你的团队希望后续把文档接入 Swagger UI、代码生成、校验或评审流程，api-documenter skill 会特别有帮助。

它真正解决的是什么问题

大多数用户并不只是“在写文档”。他们真正要做的，是把分散的 API 知识整理成一个“足够有效”的 OpenAPI 初稿，便于其他人评审、对接实现或直接发布。api-documenter 最擅长的，是你已经清楚 API 行为，只是需要把结构、完整性和一致性快速搭起来的时候。

为什么选它，而不是直接写一个普通 prompt

它的差异点不在于“深度自动化”，而在于“有引导的结构化工作流”。仓库里给了你：

• 一个清晰的 OpenAPI 3.0.3 起始模板：references/openapi-template.yaml
• 一个起步生成器：scripts/generate_openapi.py
• 一个简单校验器：scripts/validate_openapi.py
• 一些示例，帮你减少格式猜测成本

这让 api-documenter usage 比临时即兴 prompting 更可复用、更可重复；当然，前提仍然是你要提供真实的 API 细节。

它不会替你完成什么

这个 skill 不会自动发现你的在线 API，不会从代码中准确推断出所有 schema，也不会完整验证 OpenAPI 在语义层面的正确性。内置 validator 本质上是基于字符串的检查，只会确认是否包含必需章节。因此，如果你想要的是“有引导的草稿工作流”，它很合适；如果你期待“权威级 schema 自动提取”，那就不是它的定位。

如何使用 api-documenter skill

api-documenter 的安装环境与位置

这个 skill 位于 zhaono1/agent-playbook 仓库的 skills/api-documenter 目录：https://github.com/zhaono1/agent-playbook/tree/main/skills/api-documenter。

如果你的 skills 环境支持直接从 GitHub 安装，就按工具支持的远程 skill collection 安装流程来；如果不支持，就 clone 整个仓库，再让你的 agent 工具指向本地 skill 目录。常见的基础安装方式如下：

npx skills add https://github.com/zhaono1/agent-playbook --skill api-documenter

如果你的环境和这里不同，关键要求其实只有一条：agent 必须能读取 skills/api-documenter/SKILL.md 以及相关支持文件。

首次使用前建议先读哪些文件

如果你想快速上手一份 api-documenter guide，建议按这个顺序阅读：

1. SKILL.md：看激活线索和预期文档结构
2. references/openapi-template.yaml：看最小骨架长什么样
3. scripts/generate_openapi.py：看它能生成怎样的 starter file
4. scripts/validate_openapi.py：搞清楚内置检查到底验证了什么
5. references/examples/openapi-example.yaml：看一个很小但完整的示例

这个阅读顺序很重要，因为这个 repo 更像一个工作流脚手架，而不是一本文档手册。

这个 skill 需要什么输入

当你提供明确、具体的源信息时，api-documenter 表现最好，例如：

• endpoint 列表，包括 method 和 path
• 请求参数与 body 字段
• 响应示例与状态码
• 认证方式
• base URL 或环境信息
• 对象/schema 定义
• 命名规范和 tags

如果你只说一句“给这个 API 写文档”，得到的大概率只是一个通用外壳。若你能逐个 endpoint 提供事实信息，产出的草稿就会更接近可评审状态。

把模糊需求改写成有效 prompt

弱 prompt：

Create OpenAPI docs for my API.

更强的 prompt：

Use the api-documenter skill to draft an OpenAPI 3.0.3 spec for a REST API.

Base URL: https://api.example.com/v1
Auth: Bearer token in Authorization header

Endpoints:
- GET /users?page={number}&limit={number}
  - 200 returns array of User plus pagination metadata
- POST /users
  - body: name, email
  - 201 returns created User
  - 409 if email already exists
- GET /users/{id}
  - 200 returns User
  - 404 if missing

Schemas:
- User: id string, name string, email string, createdAt string(date-time)

Please include:
- summary, operationId, description, tags
- parameters and requestBody
- success and error responses
- components.schemas
- components.securitySchemes

这个更强的版本之所以有效，是因为它给了 skill 足够的结构化信息，能去填充 OpenAPI 的必需章节，而不是被迫“脑补”业务逻辑。

从零开始时，先用内置生成器搭骨架

如果你手头还没有任何 spec，先生成一个 scaffold：

python scripts/generate_openapi.py --output openapi.yaml --name users --version 1.0.0 --base-url https://api.example.com

这样做的好处是，它会先帮你产出一个语法层面结构清晰的起点，包含 info、servers、paths 和示例 schema block。之后再用这个 skill，把占位内容替换成真实的 endpoint 和 schema 细节。

校验 api-documenter 产出的内容

编辑完成后，运行内置 validator：

python scripts/validate_openapi.py --input openapi.yaml

这个 validator 本来就设计得很轻量。它只检查文件里是否出现了 openapi:、info:、servers:、paths:、components: 和 securitySchemes: 之类的必需标题。它适合用来发现“草稿还没写全”的问题，但并不能证明 spec 已经完全有效。

面向 Technical Writing 的推荐工作流

对于 api-documenter for Technical Writing，一个很实用的流程是：

1. 从工程师、代码、Postman collections 或现有文档里收集事实来源
2. 先生成或复制一个模板骨架
3. 用 endpoint 事实去提示 skill，而不是只给纯文字描述
4. 检查命名一致性、响应覆盖情况和认证细节
5. 运行 validator
6. 把 spec 交给工程师做最终评审，或放进 Swagger 工具里渲染查看

这个流程很适合技术写作者，因为 skill 可以降低结构搭建成本，而编辑判断仍然掌握在人手里。

这个 skill 看起来主要优化了什么

从仓库内容来看，它主要优化的是：

• OpenAPI 3.0.3 结构
• 完整的 endpoint 章节
• 明确区分 endpoint 字段中哪些是必需、哪些是推荐
• 能达到标准化和评审要求的文档初稿

相对来说，它并不特别适合高级多文件 spec、callbacks、webhooks、多态建模，或完整的 GraphQL schema 文档工作流。

提升输出质量的实用技巧

下面这些小动作，会明显改善 api-documenter usage 的效果：

• 用精确状态码，不要只写“handles errors”
• 每个 endpoint 至少给一个具体响应结构
• 明确字段是 required、nullable、enum-like，还是带特定格式
• 认证方式只定义一次，并要求 skill 在全局一致引用
• 尽早确定稳定的 operationId 命名方式，别等团队已经开始接入工具后再改

这些细节能避开最常见的失败模式：文档看起来漂亮，但在实际使用上非常含糊。

适合改造 api-documenter 的仓库路径

如果你想把这个 skill 调整成更贴合自己团队流程的版本，建议先看：

• skills/api-documenter/SKILL.md
• skills/api-documenter/references/openapi-template.yaml
• skills/api-documenter/scripts/generate_openapi.py
• skills/api-documenter/scripts/validate_openapi.py

按这条路径看下来，你可以一次性掌握激活规则、编写模板、初始生成逻辑和质量门槛。

api-documenter skill 常见问题

api-documenter 适合初学者吗？

适合，但前提是你已经理解自己的 API。这个 skill 能降低 OpenAPI 格式编写的摩擦成本，但不会系统地教你整套规范。对于初学者来说，只要手里有具体的 endpoint 笔记，并愿意对照模板和示例文件检查结果，就能用得比较有效。

api-documenter 只适用于 REST API 吗？

实际场景里基本可以这么理解。说明里虽然提到了 REST 或 GraphQL，但从仓库内容看，核心还是围绕 OpenAPI/Swagger 模式、示例 YAML、RESTful path 示例以及 endpoint 式文档展开。如果你的主要工作是 GraphQL schema 或 resolver 文档，这个 skill 可能不是最佳选择。

它和直接让 AI 写 API 文档有什么区别？

api-documenter 的优势在于工作流纪律性：有激活线索、可复用模板、生成脚本和校验脚本。泛用 prompt 当然也可能写得出来，但这个 skill 能给 agent 一个更明确的目标结构，减少从空白页开始时的发散和跑偏。

安装 api-documenter 后会附带完整 validator 吗？

不会。内置脚本只是一个简单的完整性检查器，不是完整的 OpenAPI parser 或 linter。如果你对严格校验有要求，建议在完成第一版草稿后，再配合专门的 OpenAPI 工具一起使用。

什么情况下不该用 api-documenter？

以下情况建议跳过 api-documenter：

• 你需要在极少人工输入下，从源代码自动提取文档
• 你的 API 主要是 GraphQL，并且需要 GraphQL 原生文档
• 你需要开箱即用的高级 spec 治理、bundling、linting 或 contract testing
• 你要的只是润色过的人类可读文档，而不是 OpenAPI 产物

技术写作者在不重度写代码的情况下能用 api-documenter 吗？

可以。它一个很强的使用场景，就是技术写作者负责收集 endpoint 事实、运行 starter script、再结合工程评审迭代 YAML。你并不需要很深的 Python 知识，照样能从这些内置脚本里获益。

如何改进 api-documenter skill

给 api-documenter 提供完整的 endpoint 事实

提升效果最明显的一点，就是把源输入质量提上来。对每个 endpoint，尽量提供：

• method 和 path
• 用途
• 参数与 body schema
• 按状态码区分的响应 schema
• 认证方式
• 边界情况或错误响应

这个 skill 很擅长把好材料组织好，但它不能替你编造可信的 API 行为。

减少 schema 描述里的歧义

很多弱质量 API 文档的问题，不在格式，而在字段含义说得不够清楚。与其只写“user object”，不如明确写成：

• id: string, immutable
• email: string, unique
• createdAt: string, date-time
• status: enum active | suspended

这样能帮助 api-documenter 生成更可复用、后续也更不容易重写的 components。

提需求时要强调覆盖率，而不只是格式

更好的修订 prompt 可以这样写：

Review this OpenAPI draft with the api-documenter skill and identify missing:
- operationId values
- requestBody schemas
- error responses
- auth declarations
- shared component schemas
Then patch the spec.

这种提示方式比单纯让模型“clean up the YAML”更能提升完整度。

留意 api-documenter 的主要失败模式

这个 skill 产出里比较常见的问题包括：

• 占位描述没有被替换掉
• 缺少 components.securitySchemes
• 错误响应覆盖过薄
• path operations 虽然有 summary，但没有真正有用的 schema 细节
• 草稿能通过内置 validator，但内容仍然不完整

提前知道这些失败模式，评审时会快很多。

把模板和你们自己的风格规范绑定起来

如果团队内部已经有命名和文档规范，最好明确写出来，例如：

• 按业务域划分 tag 名称
• operationId 的动词风格
• 分页格式
• 错误 envelope 的结构
• 日期与 enum 的约定

默认的 api-documenter skill 提供的是结构；真正让它适合生产环境的，是你们本地的这些规范。

第一版出来后继续迭代，不要重头生成

好的第二轮 prompt 往往会比第一轮更聚焦：

Using the api-documenter skill, revise this spec to normalize schema names, move repeated objects into components.schemas, and add 401/403/404 responses where applicable.

这种做法通常比从头重生更有效，因为你能保留第一版里已经有价值的结构，同时把一致性收紧。

如果这是高频工作流，就继续扩展脚本

如果你会经常使用 api-documenter，最值得投入的改进方向，就是定制这些辅助脚本。例如：

• 修改 generate_openapi.py，默认带上你们自己的 auth scheme 和 error envelope
• 扩展 validate_openapi.py，通过 --require 增加额外必需标题或 token
• 在 references/openapi-template.yaml 旁边维护一份你们自己的 starter spec

这样一来，一个通用起步工具，就能变成适合团队长期复用的文档加速器。