api-documentation-generator

API 文档生成器 - 自动生成专业开发者文档

技能概述

API 文档生成器可以从代码自动生成清晰、全面的 API 文档，包括端点说明、请求响应示例、认证详情和最佳实践指南。

适用场景

新 API 上线需要文档

当你开发完新的 REST、GraphQL 或 WebSocket API，需要快速为团队成员或外部用户生成专业文档时，这个技能可以自动分析代码结构，生成包含所有端点、参数和示例的完整文档。

现有 API 缺少清晰文档

当你的 API 已经运行但文档缺失或过时，导致新成员上手困难、外部用户频繁提问时，可以用这个技能重新生成与当前代码状态同步的准确文档。

需要 OpenAPI/Swagger 规范

当你需要导入 Postman 进行测试、对接 API 管理平台、或者满足企业文档规范要求时，这个技能可以生成符合标准的 OpenAPI/Swagger 规范文件。

核心功能

自动分析 API 结构

扫描代码库识别所有 API 端点、HTTP 方法、路由参数、请求体结构和响应格式，同时检测认证要求和错误处理模式，无需手动整理。

生成多语言调用示例

为每个端点自动生成 cURL、JavaScript（fetch/axios）、Python（requests）等多种语言的完整示例代码，方便不同技术背景的开发者快速上手。

完整的错误和认证文档

详细列出所有可能的错误码及其含义，提供故障排查指南，同时说明认证方式、令牌管理和安全最佳实践，帮助开发者正确处理异常情况。

常见问题

API 文档生成器支持哪些类型的 API？

支持 REST API、GraphQL API 和 WebSocket API。对于 REST API，可以处理所有 HTTP 方法（GET、POST、PUT、DELETE 等）；对于 GraphQL，可以查询和变更操作；对于 WebSocket，可以文档化事件和消息格式。

生成的文档包含哪些内容？

每个端点都包含 HTTP 方法和路径、认证要求、请求参数（路径、查询、请求头、请求体）、响应结构（成功和所有错误情况）、多种语言的代码示例。还包含快速开始指南、认证设置、常见用例、最佳实践、速率限制说明、分页模式和过滤排序选项。

能生成 OpenAPI/Swagger 规范吗？

可以。技能可以生成符合 OpenAPI 3.0 规范的 YAML 或 JSON 文件，可直接导入 Swagger UI、Postman、Stoplight 等工具，实现交互式文档和自动测试。