API Documentation Generator

Overview

Automatically generate clear, comprehensive API documentation from your codebase. This skill helps you create professional documentation that includes endpoint descriptions, request/response examples, authentication details, error handling, and usage guidelines.

Perfect for REST APIs, GraphQL APIs, and WebSocket APIs.

When to Use This Skill

• Use when you need to document a new API
• Use when updating existing API documentation
• Use when your API lacks clear documentation
• Use when onboarding new developers to your API
• Use when preparing API documentation for external users
• Use when creating OpenAPI/Swagger specifications

How It Works

Step 1: Analyze the API Structure

First, I'll examine your API codebase to understand: - Available endpoints and routes - HTTP methods (GET, POST, PUT, DELETE, etc.) - Request parameters and body structure - Response formats and status codes - Authentication and authorization requirements - Error handling patterns

Step 2: Generate Endpoint Documentation

For each endpoint, I'll create documentation including:

Endpoint Details: - HTTP method and URL path - Brief description of what it does - Authentication requirements - Rate limiting information (if applicable)

Request Specification: - Path parameters - Query parameters - Request headers - Request body schema (with types and validation rules)

Response Specification: - Success response (status code + body structure) - Error responses (all possible error codes) - Response headers

Code Examples: - cURL command - JavaScript/TypeScript (fetch/axios) - Python (requests) - Other languages as needed

Step 3: Add Usage Guidelines

I'll include: - Getting started guide - Authentication setup - Common use cases - Best practices - Rate limiting details - Pagination patterns - Filtering and sorting options

Step 4: Document Error Handling

Clear error documentation including: - All possible error codes - Error message formats - Troubleshooting guide - Common error scenarios and solutions

Step 5: Create Interactive Examples

Where possible, I'll provide: - Postman collection - OpenAPI/Swagger specification - Interactive code examples - Sample responses

Examples

Example 1: REST API Endpoint Documentation

## Create User

Creates a new user account.

**Endpoint:** `POST /api/v1/users`

**Authentication:** Required (Bearer token)

**Request Body:**
\`\`\`json
{
  "email": "user@example.com",      // Required: Valid email address
  "password": "SecurePass123!",     // Required: Min 8 chars, 1 uppercase, 1 number
  "name": "John Doe",               // Required: 2-50 characters
  "role": "user"                    // Optional: "user" or "admin" (default: "user")
}
\`\`\`

**Success Response (201 Created):**
\`\`\`json
{
  "id": "usr_1234567890",
  "email": "user@example.com",
  "name": "John Doe",
  "role": "user",
  "createdAt": "2026-01-20T10:30:00Z",
  "emailVerified": false
}
\`\`\`

**Error Responses:**

- `400 Bad Request` - Invalid input data
  \`\`\`json
  {
    "error": "VALIDATION_ERROR",
    "message": "Invalid email format",
    "field": "email"
  }
  \`\`\`

- `409 Conflict` - Email already exists
  \`\`\`json
  {
    "error": "EMAIL_EXISTS",
    "message": "An account with this email already exists"
  }
  \`\`\`

- `401 Unauthorized` - Missing or invalid authentication token

**Example Request (cURL):**
\`\`\`bash
curl -X POST https://api.example.com/api/v1/users \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "SecurePass123!",
    "name": "John Doe"
  }'
\`\`\`

**Example Request (JavaScript):**
\`\`\`javascript
const response = await fetch('https://api.example.com/api/v1/users', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    email: 'user@example.com',
    password: 'SecurePass123!',
    name: 'John Doe'
  })
});

const user = await response.json();
console.log(user);
\`\`\`

**Example Request (Python):**
\`\`\`python
import requests

response = requests.post(
    'https://api.example.com/api/v1/users',
    headers={
        'Authorization': f'Bearer {token}',
        'Content-Type': 'application/json'
    },
    json={
        'email': 'user@example.com',
        'password': 'SecurePass123!',
        'name': 'John Doe'
    }
)

user = response.json()
print(user)
\`\`\`

Example 2: GraphQL API Documentation

```markdown

User Query

Fetch user information by ID.

Query: ```graphql query GetUser($id: ID!) { user(id: $id) { id email name role createdAt posts { id title publishedAt } } } ```

Variables: ```json { "id": "usr_1234567890" } ```

Response: ```json { "data": { "user": { "id": "usr_1234567890", "email": "us