api-documentation-generator

用途

该技能用于从代码库自动生成清晰、全面、面向开发者的 API 文档，帮助产出包含端点描述、请求/响应示例、认证细节、错误处理和使用指南的专业文档。适用于 REST API、GraphQL API 和 WebSocket API。

适用时机

需要为新的 API 编写文档
需要更新已有的 API 文档
API 缺乏清晰文档
需要让新开发者上手了解 API
需要为外部用户准备 API 文档
需要创建 OpenAPI/Swagger 规范

工作方式

第 1 步：分析 API 结构

检查 API 代码库，了解可用端点与路由、HTTP 方法（GET、POST、PUT、DELETE 等）、请求参数与请求体结构、响应格式与状态码、认证与授权要求，以及错误处理模式。

第 2 步：生成端点文档

为每个端点创建文档，包括端点详情（HTTP 方法与 URL 路径、简要描述、认证要求、限流信息（如适用））；请求规范（路径参数、查询参数、请求头、请求体 schema 及其类型与校验规则）；响应规范（成功响应：状态码与响应体结构；错误响应：所有可能的错误码；响应头）；代码示例（cURL、JavaScript/TypeScript（fetch/axios）、Python（requests）及其他按需语言）。

第 3 步：补充使用指南

包含快速入门指南、认证设置、常见用例、最佳实践、限流细节、分页模式、过滤与排序选项。

第 4 步：编写错误处理文档

清晰记录所有可能的错误码、错误消息格式、故障排查指南，以及常见错误场景与解决方案。

第 5 步：创建交互式示例

在可能的情况下提供 Postman 集合、OpenAPI/Swagger 规范、交互式代码示例与示例响应。

示例

示例 1：REST API 端点文档

以创建用户端点为例，文档包含端点 POST /api/v1/users、认证要求（Bearer token）、请求体 JSON 及字段说明、成功响应（201 Created）和错误响应（400、409、401），以及 cURL、JavaScript、Python 的请求示例。

示例 2：GraphQL API 文档

以按 ID 获取用户信息的查询为例，展示 GraphQL 查询语句、变量、响应与错误格式。

示例 3：认证文档

说明所有 API 请求需使用 Bearer token 认证，包含获取令牌端点 POST /api/v1/auth/login、请求与响应示例、令牌使用方式（Authorization: Bearer YOUR_TOKEN）、令牌过期与刷新端点 POST /api/v1/auth/refresh。

最佳实践

应做到：保持一致格式；包含可运行的多语言代码示例；记录所有可能的错误码及含义；使用真实示例数据；解释每个参数的作用与约束；为 API 添加版本号（如 /api/v1/）；标注文档最后更新时间；链接相关端点；记录限流策略；提供 Postman 集合。

应避免：跳过错误情况；使用模糊描述（如“获取数据”）；遗漏认证要求；忽略边界情况（分页、过滤、排序）；留下无法运行的示例；使用过时信息；过度复杂化；遗漏重要响应头。

文档结构建议

可包含的章节：介绍（API 功能、基础 URL、API 版本、支持联系方式）；认证（如何认证、令牌管理、安全最佳实践）；快速开始（简单示例、常见用例演示）；端点（按资源组织、每个端点完整细节）；数据模型（schema 定义、字段说明、校验规则）；错误处理（错误码参考、错误响应格式、故障排查指南）；限流（限制与配额、需检查的响应头、处理限流错误）；变更日志（API 版本历史、破坏性变更、弃用通知）；SDK 与工具（官方客户端库、Postman 集合、OpenAPI 规范）。

常见问题与解决思路

文档与代码不同步：由代码注释/注解生成文档；使用 Swagger/OpenAPI 等工具；添加验证文档的 API 测试；每次 API 变更时审查文档。
缺少错误文档：记录每个可能的错误码；提供清晰错误消息；包含排查步骤；展示示例错误响应。
示例无法运行：测试每个代码示例；使用真实可用的端点；提供完整示例而非片段；提供沙箱环境。
参数要求不清晰：明确标注必填与可选；说明数据类型与格式；展示校验规则；提供示例值。

工具与格式

OpenAPI/Swagger：可生成交互式文档（示例给出 openapi: 3.0.0 结构）。
Postman 集合：可导出集合便于测试（示例给出集合 JSON 结构）。

提示

尽量让 API 文档贴近代码，使用可从代码注释生成文档的工具，以确保两者保持同步。

技能介绍

用途