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

## 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": "use

api-documentation-generator

Documentation

API Documentation Generator

Overview

When to Use This Skill

How It Works

Step 1: Analyze the API Structure

Step 2: Generate Endpoint Documentation

Step 3: Add Usage Guidelines

Step 4: Document Error Handling

Step 5: Create Interactive Examples

Examples

Example 1: REST API Endpoint Documentation

Example 2: GraphQL API Documentation

Use Cases

Quick Info

Tags

Related Skills

ab-test-setup

airflow-dag-patterns

algorithmic-art