Api Documentation Generator

# 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@ex