api-documentation-generator

name	api-documentation-generator
description	Generate comprehensive, developer-friendly API documentation from code, including endpoints, parameters, examples, and best practices

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": "[e-mail]",      // 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": "[e-mail]",
  "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": "[e-mail]",
    "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: '[e-mail]',
    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': '[e-mail]',
        '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": "[e-mail]",
      "name": "John Doe",
      "role": "user",
      "createdAt": "2026-01-20T10:30:00Z",
      "posts": [
        {
          "id": "post_123",
          "title": "My First Post",
          "publishedAt": "2026-01-21T14:00:00Z"
        }
      ]
    }
  }
}
\`\`\`

**Errors:**
\`\`\`json
{
  "errors": [
    {
      "message": "User not found",
      "extensions": {
        "code": "USER_NOT_FOUND",
        "userId": "usr_1234567890"
      }
    }
  ]
}
\`\`\`

Example 3: Authentication Documentation

## Authentication

All API requests require authentication using Bearer tokens.

### Getting a Token

**Endpoint:** `POST /api/v1/auth/login`

**Request:**
\`\`\`json
{
  "email": "[e-mail]",
  "password": "your-password"
}
\`\`\`

**Response:**
\`\`\`json
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiresIn": 3600,
  "refreshToken": "refresh_token_here"
}
\`\`\`

### Using the Token

Include the token in the Authorization header:

\`\`\`
Authorization: Bearer YOUR_TOKEN
\`\`\`

### Token Expiration

Tokens expire after 1 hour. Use the refresh token to get a new access token:

**Endpoint:** `POST /api/v1/auth/refresh`

**Request:**
\`\`\`json
{
  "refreshToken": "refresh_token_here"
}
\`\`\`

Best Practices

✅ Do This

• Be Consistent - Use the same format for all endpoints
• Include Examples - Provide working code examples in multiple languages
• Document Errors - List all possible error codes and their meanings
• Show Real Data - Use realistic example data, not "foo" and "bar"
• Explain Parameters - Describe what each parameter does and its constraints
• Version Your API - Include version numbers in URLs (/api/v1/)
• Add Timestamps - Show when documentation was last updated
• Link Related Endpoints - Help users discover related functionality
• Include Rate Limits - Document any rate limiting policies
• Provide Postman Collection - Make it easy to test your API

❌ Don't Do This

• Don't Skip Error Cases - Users need to know what can go wrong
• Don't Use Vague Descriptions - "Gets data" is not helpful
• Don't Forget Authentication - Always document auth requirements
• Don't Ignore Edge Cases - Document pagination, filtering, sorting
• Don't Leave Examples Broken - Test all code examples
• Don't Use Outdated Info - Keep documentation in sync with code
• Don't Overcomplicate - Keep it simple and scannable
• Don't Forget Response Headers - Document important headers

Documentation Structure

Recommended Sections

1. Introduction

   • What the API does
   • Base URL
   • API version
   • Support contact

2. Authentication

   • How to authenticate
   • Token management
   • Security best practices

3. Quick Start

   • Simple example to get started
   • Common use case walkthrough

4. Endpoints

   • Organized by resource
   • Full details for each endpoint

5. Data Models

   • Schema definitions
   • Field descriptions
   • Validation rules

6. Error Handling

   • Error code reference
   • Error response format
   • Troubleshooting guide

7. Rate Limiting

   • Limits and quotas
   • Headers to check
   • Handling rate limit errors

8. Changelog

   • API version history
   • Breaking changes
   • Deprecation notices

9. SDKs and Tools

   • Official client libraries
   • Postman collection
   • OpenAPI specification

Common Pitfalls

Problem: Documentation Gets Out of Sync

Symptoms: Examples don't work, parameters are wrong, endpoints return different data Solution:

• Generate docs from code comments/annotations
• Use tools like Swagger/OpenAPI
• Add API tests that validate documentation
• Review docs with every API change

Problem: Missing Error Documentation

Symptoms: Users don't know how to handle errors, support tickets increase Solution:

• Document every possible error code
• Provide clear error messages
• Include troubleshooting steps
• Show example error responses

Problem: Examples Don't Work

Symptoms: Users can't get started, frustration increases Solution:

• Test every code example
• Use real, working endpoints
• Include complete examples (not fragments)
• Provide a sandbox environment

Problem: Unclear Parameter Requirements

Symptoms: Users send invalid requests, validation errors Solution:

• Mark required vs optional clearly
• Document data types and formats
• Show validation rules
• Provide example values

Tools and Formats

OpenAPI/Swagger

Generate interactive documentation:

openapi: 3.0.0
info:
  title: My API
  version: 1.0.0
paths:
  /users:
    post:
      summary: Create a new user
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUserRequest'

Postman Collection

Export collection for easy testing:

{
  "info": {
    "name": "My API",
    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
  },
  "item": [
    {
      "name": "Create User",
      "request": {
        "method": "POST",
        "url": "{{baseUrl}}/api/v1/users"
      }
    }
  ]
}

Related Skills

• @doc-coauthoring - For collaborative documentation writing
• @copywriting - For clear, user-friendly descriptions
• @test-driven-development - For ensuring API behavior matches docs
• @systematic-debugging - For troubleshooting API issues

Additional Resources

• OpenAPI Specification
• REST API Best Practices
• GraphQL Documentation
• API Design Patterns
• Postman Documentation

---

Pro Tip: Keep your API documentation as close to your code as possible. Use tools that generate docs from code comments to ensure they stay in sync!