api-documentation-writer（API 文档写作）

API Documentation Writer

Create comprehensive, developer-friendly API documentation.

Instructions

When a user needs API documentation:

1. Gather API Information:

- API type (REST, GraphQL, WebSocket, gRPC)? - Authentication method (API key, OAuth, JWT)? - Base URL and versioning strategy? - Available endpoints and their purposes? - Request/response formats? - Rate limiting or usage restrictions?

1. Generate Complete Documentation Structure: Overview Section: Authentication: Base URL & Versioning: Endpoints (for each endpoint): Error Handling: Rate Limiting: SDKs & Libraries: Webhooks (if applicable):

- What the API does (1-2 sentences) - Key capabilities - Getting started checklist - Support and resources - How to obtain credentials - Where to include auth tokens - Example authenticated request - Token refresh process (if applicable) - Production and sandbox URLs - Version format (path, header, query param) - Current version and changelog link - HTTP method and path - Description of what it does - Path parameters - Query parameters - Request headers - Request body schema - Response codes and meanings - Response body schema - Example request (curl, JavaScript, Python) - Example response (formatted JSON) - Standard error response format - Common error codes and meanings - Troubleshooting guide - Limits and windows - Headers to check - How to handle rate limit errors - Official client libraries - Community libraries - Installation instructions - Available webhook events - Setup process - Payload examples - Security verification

1. Format Output (REST API example): ` # [API Name] Documentation ## Overview [Brief description of what the API does] **Base URL**: https://api.example.com/v1 **Authentication**: API Key via Authorization header ## Quick Start 1. [Step 1] 2. [Step 2] 3. [Step 3] ## Authentication All requests require an API key in the Authorization header: Authorization: Bearer YOUR_API_KEY `` Get your API key from [dashboard link]. ## Endpoints ### GET /resource Retrieve a list of resources. **Parameters**: - limit (optional, integer): Number of results (max 100, default 10) - offset (optional, integer): Pagination offset (default 0) - filter (optional, string): Filter by field **Request Example**: `bash curl -X GET "https://api.example.com/v1/resource?limit=10" \ -H "Authorization: Bearer YOUR_API_KEY" `` **Response** (200 OK): {"data": [{"id": "123", "name": "Example", "created_at": "2024-01-15T10:00:00Z"}], "total": 100, "limit": 10, "offset": 0} **Response Codes**: POST /resource Create a new resource. **Request Body**: {"name": "string (required)", "description": "string (optional)", "metadata": "object (optional)"} **Request Example**: curl -X POST "https://api.example.com/v1/resource" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"name": "My Resource", "description": "A test resource"}' **Response** (201 Created): {"id": "124", "name": "My Resource", "description": "A test resource", "created_at": "2024-01-15T10:30:00Z"} Error Handling All errors follow this format: {"error": {"code": "invalid_request", "message": "The 'name' field is required", "details": {"field": "name"}}} **Common Error Codes**: Rate Limiting **Limits**: 1000 requests per hour **Headers**: When rate limited, you'll receive a 429 status code. Code Examples JavaScript (Node.js) const response = await fetch('https://api.example.com/v1/resource', {headers: {'Authorization': 'Bearer YOUR_API_KEY'}}); const data = await response.json(); Python import requests response = requests.get('https://api.example.com/v1/resource', headers={'Authorization': 'Bearer YOUR_API_KEY'}) data = response.json() Support `

- 200 - Success - 400 - Bad request (invalid parameters) - 401 - Unauthorized (invalid API key) - 429 - Rate limit exceeded - 500 - Server error - invalid_request - Malformed request - authentication_failed - Invalid API key - not_found - Resource doesn't exist - rate_limit_exceeded - Too many requests - internal_error - Server error - X-RateLimit-Limit: Total requests allowed - X-RateLimit-Remaining: Requests remaining - X-RateLimit-Reset: Timestamp when limit resets - Documentation: https://docs.example.com - Support: support@example.com - Status: https://status.example.com

1. For GraphQL APIs, adapt to show:

- Schema definitions - Query examples - Mutation examples - Subscription examples - Variables and directives

1. Documentation Best Practices:

- Start with working example (copy-paste ready) - Show both request and response - Use realistic example data - Include error cases - Explain every parameter - Provide code examples in multiple languages - Use consistent formatting - Add "Try it" interactive examples when possible - Link related endpoints - Include changelog and versioning

1. Developer Experience Tips:

- Include a "Quick Start" with working example in 60 seconds - Provide Postman collection or OpenAPI spec - Show common use cases and workflows - Include troubleshooting section - Add testing/sandbox environment - Provide SDKs with installation instructions - Include rate limiting details upfront - Show pagination patterns - Explain filtering and sorting options

Example Triggers

• "Write API documentation for my REST endpoints"
• "Create OpenAPI spec for my API"
• "Document this GraphQL schema"
• "Generate developer docs for my webhook API"
• "Write authentication guide for API"

Output Quality

Ensure documentation:

• Starts with working example
• Explains every parameter and field
• Shows realistic request/response examples
• Includes error handling
• Provides code samples in multiple languages
• Uses consistent formatting
• Is organized logically (most common operations first)
• Includes authentication clearly
• Covers edge cases and limitations
• Follows REST/GraphQL best practices
• Is scannable with good use of headers
• Includes interactive examples when possible

Generate comprehensive, developer-friendly API documentation that makes integration effortless.