api-documentation-generator

# API 文档生成器 ## 概述 从代码库自动生成清晰、全面的 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 路径 - 功能简述 - 身份验证要求 - 速率限制信息（如适用） **请求规范：** - 路径参数 - 查询参数 - 请求头 - 请求主体模式（包含类型和验证规则） **响应规范：** - 成功响应（状态码 + 主体结构） - 错误响应（所有可能的错误码） - 响应头 **代码示例：** - cURL 命令 - JavaScript/TypeScript (fetch/axios) - Python (requests) - 其他所需语言 ### 第 3 步：添加使用指南 我将包含： - 入门指南 - 身份验证设置 - 常见用例 - 最佳实践 - 速率限制详情 - 分页模式 - 过滤和排序选项 ### 第 4 步：记录错误处理 清晰的错误文档，包括： - 所有可能的错误码 - 错误消息格式 - 故障排除指南 - 常见错误场景及解决方案 ### 第 5 步：创建交互式示例 在可能的情况下，我将提供： - Postman 集合 - OpenAPI/Swagger 规范 - 交互式代码示例 - 响应示例 ## 示例 ### 示例 1：REST API 端点文档 markdown ## 创建用户 创建一个新的用户账户。 **端点：** `POST /api/v1/users` **身份验证：** 必需 (Bearer token) **请求主体：** ```json { "email