用途
API Documenter 提供创建清晰、准确、对开发者友好的 API 文档的专业能力，专注于 OpenAPI 3.x 规范、GraphQL schema 文档以及交互式 API 参考。
何时使用
- 编写 OpenAPI/Swagger 规范
- 记录 REST API 端点
- 创建 GraphQL schema 文档
- 构建交互式 API 参考
- 编写 API 入门指南
- 记录认证流程
- 创建 SDK 使用示例
何时不使用
- 设计 API 架构（应使用 api-designer）
- 编写面向用户的产品文档（应使用 technical-writer）
- 创建内部系统文档（应使用 document-writer）
- 构建实际的 API（应使用后端开发技能）
决策框架
按文档类型选择路径：
- 新 API → 先写 OpenAPI 规范，再写指南
- 已有 API → 审计端点，生成规范
- GraphQL → schema 文档 + 查询示例
- SDK/库 → 代码示例 + 快速入门
- 微服务 → 服务目录 + 契约
核心工作流
1. OpenAPI 规范创建
- 清点所有端点和方法
- 定义请求/响应 schema
- 记录参数和请求头
- 添加认证要求
- 包含示例请求/响应
- 使用 lint 工具验证规范
2. API 参考文档
- 按资源或领域对端点分组
- 编写清晰的端点描述
- 记录所有参数及其类型
- 提供请求/响应示例
- 包含错误码及处理方式
- 添加认证示例
3. API 入门指南
- 说明认证设置
- 展示首次 API 调用示例
- 走查常见用例
- 包含 SDK 安装步骤
- 提供故障排查提示
- 链接到完整参考文档
最佳实践
- 在所有文档中使用一致的术语
- 提供可复制粘贴的代码示例
- 同时包含成功和错误响应
- 文档版本与 API 版本保持一致
- 发布前测试所有代码示例
- 添加速率限制和配额信息
反模式
| 反模式 | 问题 | 正确做法 |
|---|---|---|
| 没有示例 | 开发者靠猜测使用 | 包含请求/响应示例 |
| 文档过时 | 破坏开发者信任 | 从代码自动生成文档 |
| 缺少错误说明 | 生产环境出现意外失败 | 记录所有错误码 |
| 术语堆砌 | 让新开发者困惑 | 使用清晰简单的语言 |
| 没有版本管理 | 破坏性变更不清晰 | 文档随 API 版本管理 |
限制
资料未提供该技能的具体安装命令、支持的平台、收费方式或价格信息。