api-documentation

API 文档

为多种 API 协议（包括 REST/HTTP、gRPC、GraphQL 和 RPC）生成全面、交互式的 API 文档。这项技能有助于创建准确、及时且对开发者和使用者都有用的文档。

何时使用

在以下情况下使用这项技能：

• 需要为内部或外部使用者编写 API 文档
• 有多种 API 协议（REST、gRPC、GraphQL、RPC），需要统一编写文档
• 希望根据代码或 API 定义自动生成文档
• 需要具备测试功能的交互式文档
• 正在为公开发布或开发者门户准备 API 文档
• 需要确保多个 API 版本的文档保持一致
• 希望提升 API 的可发现性和易用性

我能做什么

• 多协议支持：为 REST/HTTP、gRPC、GraphQL 和 RPC API 生成文档
• 代码优先的文档编写：从代码注释、OpenAPI/Swagger、Protobuf、GraphQL 架构中提取文档
• 交互式示例：创建可执行且具备测试功能的 API 示例
• 版本管理：管理多个 API 版本并提供迁移指南
• 一致性检查：确保 API 实现与文档保持一致
• 文档生成：生成 HTML、Markdown、PDF 和交互式 API 控制台
• 身份验证文档：记录身份验证方法（OAuth、API 密钥、JWT）
• 错误处理文档：记录错误代码、消息和故障排查方法
• 速率限制文档：记录速率限制、配额和使用政策

示例

# Generate OpenAPI documentation from code
./scripts/analyze-api-docs.sh --source src/ --format openapi

# Generate gRPC documentation from Protobuf files
./scripts/analyze-api-docs.sh --source proto/ --format grpc

# Generate GraphQL schema documentation
./scripts/analyze-api-docs.sh --source schema.graphql --format graphql

# Generate comprehensive API portal
./scripts/analyze-api-docs.sh --portal --output docs/api-portal

# Check documentation consistency
./scripts/analyze-api-docs.sh --consistency-check --api implementations/

输出格式

API Documentation Analysis
─────────────────────────────────────
API Protocol: REST/HTTP
Source Files: 42
Endpoints Documented: 127/142 (89%)

DOCUMENTATION QUALITY METRICS:
───────────────────────────────
✅ Complete: Authentication documented (OAuth 2.0, API keys)
✅ Complete: Error responses documented (25 error codes)
✅ Complete: Request/response examples provided
⚠️ Needs Improvement: Rate limiting documentation missing
⚠️ Needs Improvement: 15 endpoints missing parameter descriptions
❌ Missing: Version migration guide for v1 → v2

API DISCOVERABILITY:
────────────────────
• Endpoints grouped by resource (Users, Products, Orders)
• Search functionality available
• Interactive testing console enabled
• SDK generation for 5 languages (JavaScript, Python, Go, Java, C#)

MULTI-PROTOCOL ANALYSIS:
────────────────────────
REST/HTTP APIs: 142 endpoints
  • OpenAPI specification: Complete
  • Interactive docs: Available via Swagger UI
  • Testing examples: 85%

gRPC APIs: 28 services
  • Protobuf documentation: Complete
  • gRPC reflection: Enabled
  • Client libraries: Generated for 3 languages

GraphQL APIs: 1 schema
  • GraphQL schema: Documented
  • GraphiQL interface: Available
  • Queries/Mutations: 47 operations documented

RPC APIs: 12 methods
  • JSON-RPC documentation: Partial
  • WebSocket support: Documented
  • Binary protocols: Not documented

CONSISTENCY ISSUES (3):
────────────────────────
1. Endpoint /api/v1/users/{id}/profile missing from OpenAPI spec
2. gRPC service "PaymentService" missing authentication documentation
3. GraphQL field "Product.inventory" description inconsistent with REST API

RECOMMENDATIONS:
────────────────
1. HIGH PRIORITY: Document rate limiting policies for all endpoints
2. HIGH PRIORITY: Add version migration guide for upcoming v2 release
3. MEDIUM PRIORITY: Complete JSON-RPC documentation for remaining 5 methods
4. MEDIUM PRIORITY: Generate SDKs for additional languages (Ruby, PHP, Swift)
5. LOW PRIORITY: Add deprecation notices for endpoints scheduled for removal

GENERATED ARTIFACTS:
────────────────────
• OpenAPI 3.0 specification: openapi.yaml
• Interactive API console: docs/api-console/index.html
• Client SDKs: sdk/javascript/, sdk/python/, sdk/go/
• API reference PDF: docs/api-reference.pdf
• Postman collection: docs/postman-collection.json
• cURL examples: docs/curl-examples.md

注意事项

• 文档应尽可能贴近代码生成
• 交互式文档有助于提高 API 采用率并减少支持请求
• API 实现与文档保持一致至关重要
• 应将文档视为 API 开发生命周期的一部分
• 不同的 API 协议可能需要不同的文档编写方法
• 版本管理有助于使用者在不同 API 版本之间迁移
• 身份验证和错误处理是最常查阅的部分
• 定期审阅文档有助于确保其准确、完整