| name | api-documentation-writer |
| description | Generate comprehensive API documentation for REST, GraphQL, WebSocket APIs with OpenAPI specs, endpoint descriptions, request/response examples, error codes, authentication guides, and SDKs. USE WHEN user says 'viết document API', 'tạo API docs', 'generate API documentation', 'document REST endpoints', hoặc cần tạo technical reference cho developers. |
When to Activate This Skill
- User nói "viết document API"
- User muốn "tạo API documentation"
- Cần generate "OpenAPI spec"
- Cần document "GraphQL schema"
- Cần tạo "developer guide" cho API
- Cần document "webhook" hoặc "authentication"
Core Workflow
Phase 1: Gather API Information
Hỏi user những câu hỏi sau để hiểu rõ API:
- API type: REST, GraphQL, WebSocket, gRPC?
- Authentication: API key, OAuth, JWT, Bearer token?
- Base URL: Production URL, versioning strategy?
- Endpoints: Danh sách endpoints, mục đích của từng cái?
- Request/Response format: JSON, XML, custom format?
- Rate limiting: Có giới hạn không, bao nhiêu requests/giờ?
- Webhooks: Có support webhooks không?
Phase 2: Generate Complete Documentation Structure
Overview Section:
- Mô tả API (1-2 câu)
- Key capabilities
- Quick start checklist
- Support & resources
Authentication:
- Cách lấy credentials
- Nơi đặt auth tokens
- Example authenticated request
- Token refresh process (nếu có)
Base URL & Versioning:
- Production + sandbox URLs
- Version format (path, header, query param)
- Current version + changelog
Endpoints (mỗi endpoint):
- HTTP method + path
- Mô tả chi tiết
- Path parameters
- Query parameters
- Request headers
- Request body schema
- Response codes + meanings
- Response body schema
- Example requests (curl, JavaScript, Python)
- Example responses (formatted JSON)
Error Handling:
- Standard error response format
- Common error codes + meanings
- Troubleshooting guide
Rate Limiting:
- Limits + windows
- Headers to check
- How to handle rate limits
SDKs & Libraries:
- Official client libraries
- Community libraries
- Installation instructions
Webhooks (nếu có):
- Available webhook events
- Setup process
- Payload examples
- Security verification
Phase 3: Format Output
REST API Template:
Phase 2 details: read .claude/skills/api/api-documentation-writer/references/phase2-structure.md
