api-documentation-writer

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