api-documentation

API ドキュメント

REST/HTTP、gRPC、GraphQL、RPC など、複数の API プロトコルに対応した、包括的でインタラクティブな 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 のバージョン間を移行しやすくなります
• 認証とエラー処理は、特に参照されることの多いセクションです
• ドキュメントを定期的にレビューすると、正確性と網羅性を保ちやすくなります