api-documentation

用途

API Documentation 是一项帮助生成专业 API 文档的技能，目标是让文档清晰、完整且易于使用，既服务开发者，也服务非技术相关方。它可用于生成和整理包含端点描述、请求与响应示例、参数文档与校验规则、认证与授权细节、错误码与排查说明、多语言代码示例以及交互式示例在内的 API 文档。

主要能力

根据官方资料，该技能具备以下关键特性：

全面覆盖：记录端点、参数、响应与错误。
多种格式：生成 OpenAPI 3.0、Markdown 或 HTML 文档。
代码示例：包含 Python、JavaScript、cURL 等语言的示例。
交互式：可添加可运行示例与 API 浏览器。
结构清晰：使用一致的结构与明确的分类。
版本控制：跟踪 API 变更与废弃情况。
团队友好：便于开发者贡献和更新文档。

适用场景

官方资料指出，在以下情况下可使用该技能：

文档化 REST 或 GraphQL API
创建 OpenAPI/Swagger 规范
生成 SDK 文档
为团队构建内部 API 指南
创建开发者门户
维护最新的端点参考
文档化 Webhook 规范

使用方式

官方给出的使用步骤为：

提供 API 详情：给出端点 URL、方法和用途。
记录参数：说明必填/可选参数、类型与约束。
包含示例：提供真实世界的请求与响应示例。
定义错误：列出可能的错误码及其含义。
添加上下文：说明认证、速率限制和使用模式。
生成输出：按偏好格式创建文档。
审阅与迭代：打磨示例并澄清模糊部分。

官方指南还建议：使用具体示例而非通用占位符；保持文档与实际 API 行为同步；像用户一样思考，记录常见工作流和用例；包含边界情况，突出错误条件和限制；在适用时遵循 OpenAPI/AsyncAPI 规范；按逻辑组织内容，将相关端点和资源分组；提供基础与高级两种使用路径。

示例

官方提供了一个 REST API 端点文档示例：创建用户。

端点：POST /api/v1/users

描述：使用提供的信息创建新的用户账户。

认证：Bearer Token（必填）

请求：

{
  "email": "user@example.com",
  "name": "John Doe",
  "role": "developer"
}

响应（201 Created）：

{
  "id": "usr_12345",
  "email": "user@example.com",
  "name": "John Doe",
  "role": "developer",
  "created_at": "2024-01-15T10:30:00Z"
}

错误响应（400 Bad Request）：

{
  "error": "INVALID_EMAIL",
  "message": "The provided email is invalid",
  "field": "email"
}

另一个示例是生成 OpenAPI 规范。输入为端点列表，例如路径 /api/products、方法 GET、描述 List all products，以及名为 limit、类型 integer、非必填、默认值为 20 的参数。输出为格式正确的 OpenAPI 3.0 YAML 规范，包含所有端点、模式和示例。

模板与脚本

该技能包含以下模板：

endpoint-template.md - 单端点文档
api-overview.md - 完整 API 指南
error-codes.md - 错误参考
authentication-guide.md - 认证模式与流程

辅助脚本包括：

validate-api.py - 根据文档校验 API 端点
generate-openapi.py - 将规范转换为 OpenAPI 格式
format-examples.py - 统一代码示例格式

最佳实践

官方列出的最佳实践包括：发布前记录所有端点；保持示例最新且经过测试；包含 SDK 与客户端库链接；提供沙箱/测试端点；维护 API 版本的变更日志；支持多种认证方式；如适用则包含 Webhook 文档。

常见模式

官方给出的 API 文档模式与复杂度对应关系为：REST 适用于通用 API，复杂度低；GraphQL 适用于复杂数据查询，复杂度高；gRPC 适用于高性能服务，复杂度高；WebSocket 适用于实时通信，复杂度中；OpenAPI 用于标准化规范，复杂度中。

支持与限制

官方列出的相关资源包括 OpenAPI 3.0 规范、API 文档最佳实践、代码示例模板和校验工具。需要帮助时，可查阅上方示例、查看 assets/templates/ 中的模板、使用 scripts/ 中的校验工具，并参考最佳实践指南。

关于该技能的收费、价格、平台与具体效果，官方资料中暂未提供。