name: api-documentation-writer
description: Generate comprehensive API documentation including endpoint descriptions, request/response examples, authentication guides, error codes, and SDKs. Creates OpenAPI/Swagger specs, REST API docs, and developer-friendly reference materials. Use when users need to document APIs, create technical references, or write developer documentation.

API Documentation Writer

Create comprehensive, developer-friendly API documentation.

Instructions

When a user needs API documentation:

1. Gather API Information:
2. API type (REST, GraphQL, WebSocket, gRPC)?
3. Authentication method (API key, OAuth, JWT)?
4. Base URL and versioning strategy?
5. Available endpoints and their purposes?
6. Request/response formats?

7. Rate limiting or usage restrictions?

8. Generate Complete Documentation Structure:

Overview Section:
- What the API does (1-2 sentences)
- Key capabilities
- Getting started checklist
- Support and resources

Authentication:
- How to obtain credentials
- Where to include auth tokens
- Example authenticated request
- Token refresh process (if applicable)

Base URL & Versioning:
- Production and sandbox URLs
- Version format (path, header, query param)
- Current version and changelog link

Endpoints (for each endpoint):
- 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)

Error Handling:
- Standard error response format
- Common error codes and meanings
- Troubleshooting guide

Rate Limiting:
- Limits and windows
- Headers to check
- How to handle rate limit errors

SDKs & Libraries:
- Official client libraries
- Community libraries
- Installation instructions

Webhooks (if applicable):
- Available webhook events
- Setup process
- Payload examples
- Security verification

1. Format Output (REST API example):
   ```markdown
   # [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):
json { "data": [ { "id": "123", "name": "Example", "created_at": "2024-01-15T10:00:00Z" } ], "total": 100, "limit": 10, "offset": 0 }

Response Codes:
- 200 - Success
- 400 - Bad request (invalid parameters)
- 401 - Unauthorized (invalid API key)
- 429 - Rate limit exceeded
- 500 - Server error

### POST /resource

Create a new resource.

Request Body:
json { "name": "string (required)", "description": "string (optional)", "metadata": "object (optional)" }

Request Example:
bash 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):
json { "id": "124", "name": "My Resource", "description": "A test resource", "created_at": "2024-01-15T10:30:00Z" }

## Error Handling

All errors follow this format:

json { "error": { "code": "invalid_request", "message": "The 'name' field is required", "details": { "field": "name" } } }

Common Error Codes:
- 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

## Rate Limiting

Limits: 1000 requests per hour

Headers:
- X-RateLimit-Limit: Total requests allowed
- X-RateLimit-Remaining: Requests remaining
- X-RateLimit-Reset: Timestamp when limit resets

When rate limited, you'll receive a 429 status code.

## Code Examples

### JavaScript (Node.js)
javascript const response = await fetch('https://api.example.com/v1/resource', { headers: { 'Authorization': 'Bearer YOUR_API_KEY' } }); const data = await response.json();

### Python
```python
import requests

response = requests.get(
'https://api.example.com/v1/resource',
headers={'Authorization': 'Bearer YOUR_API_KEY'}
)
data = response.json()
```

## Support

• Documentation: https://docs.example.com
• Support: [email protected]

• Status: https://status.example.com
  ```

• For GraphQL APIs, adapt to show:

• Schema definitions
• Query examples
• Mutation examples
• Subscription examples

• Variables and directives

• 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

• 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.