// 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.
| 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. |
Create comprehensive, developer-friendly API documentation.
When a user needs API documentation:
Gather API Information:
Generate Complete Documentation Structure:
Overview Section:
Authentication:
Base URL & Versioning:
Endpoints (for each endpoint):
Error Handling:
Rate Limiting:
SDKs & Libraries:
Webhooks (if applicable):
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:
200 - Success400 - Bad request (invalid parameters)401 - Unauthorized (invalid API key)429 - Rate limit exceeded500 - Server errorCreate 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"
}
All errors follow this format:
{
"error": {
"code": "invalid_request",
"message": "The 'name' field is required",
"details": {
"field": "name"
}
}
}
Common Error Codes:
invalid_request - Malformed requestauthentication_failed - Invalid API keynot_found - Resource doesn't existrate_limit_exceeded - Too many requestsinternal_error - Server errorLimits: 1000 requests per hour
Headers:
X-RateLimit-Limit: Total requests allowedX-RateLimit-Remaining: Requests remainingX-RateLimit-Reset: Timestamp when limit resetsWhen rate limited, you'll receive a 429 status code.
const response = await fetch('https://api.example.com/v1/resource', {
headers: {
'Authorization': 'Bearer YOUR_API_KEY'
}
});
const data = await response.json();
import requests
response = requests.get(
'https://api.example.com/v1/resource',
headers={'Authorization': 'Bearer YOUR_API_KEY'}
)
data = response.json()
For GraphQL APIs, adapt to show:
Documentation Best Practices:
Developer Experience Tips:
Ensure documentation:
Generate comprehensive, developer-friendly API documentation that makes integration effortless.