API Documentation

API Documentation Skill

Auto-generate comprehensive API documentation with examples, schemas, and interactive tools.

Instructions

You are an API documentation expert. When invoked:

1. Generate Documentation:

   • Create API reference documentation
   • Extract info from code comments
   • Generate from OpenAPI/Swagger specs
   • Include usage examples
   • Document authentication methods

2. Interactive Documentation:

   • Set up Swagger UI
   • Configure Redoc
   • Create interactive playgrounds
   • Add try-it-out features
   • Include code samples

3. Documentation Types:

   • API reference guides
   • Getting started tutorials
   • Authentication guides
   • Error handling documentation
   • Rate limiting policies

4. Multi-Format Export:

   • HTML documentation
   • Markdown files
   • PDF exports
   • Postman collections
   • SDK generation

Usage Examples

@api-documentation
@api-documentation --from-openapi
@api-documentation --interactive
@api-documentation --export-postman
@api-documentation --generate-sdk

Documentation Tools

Swagger UI

Setup with Express

const express = require('express');
const swaggerUi = require('swagger-ui-express');
const YAML = require('yamljs');

const app = express();

// Load OpenAPI spec
const swaggerDocument = YAML.load('./openapi.yaml');

// Serve Swagger UI
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument, {
  customCss: '.swagger-ui .topbar { display: none }',
  customSiteTitle: 'My API Documentation',
  customfavIcon: '/favicon.ico'
}));

// Serve OpenAPI spec as JSON
app.get('/openapi.json', (req, res) => {
  res.json(swaggerDocument);
});

app.listen(3000, () => {
  console.log('API docs available at http://localhost:3000/api-docs');
});

Custom Swagger Options

const options = {
  explorer: true,
  swaggerOptions: {
    persistAuthorization: true,
    displayRequestDuration: true,
    filter: true,
    syntaxHighlight: {
      activate: true,
      theme: 'monokai'
    }
  },
  customCss: `
    .swagger-ui .topbar { background-color: #2c3e50; }
    .swagger-ui .info .title { color: #2c3e50; }
  `,
  customSiteTitle: 'My API - Documentation',
  customfavIcon: '/assets/favicon.ico'
};

app.use('/docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument, options));

Redoc

Setup

const express = require('express');
const { createProxyMiddleware } = require('http-proxy-middleware');

const app = express();

// Serve OpenAPI spec
app.get('/openapi.yaml', (req, res) => {
  res.sendFile(__dirname + '/openapi.yaml');
});

// Serve Redoc
app.get('/docs', (req, res) => {
  res.send(`
    <!DOCTYPE html>
    <html>
      <head>
        <title>API Documentation</title>
        <meta charset="utf-8"/>
        <meta name="viewport" content="width=device-width, initial-scale=1">
        <link href="https://fonts.googleapis.com/css?family=Montserrat:300,400,700|Roboto:300,400,700" rel="stylesheet">
        <style>
          body { margin: 0; padding: 0; }
        </style>
      </head>
      <body>
        <redoc spec-url='/openapi.yaml'></redoc>
        <script src="https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js"></script>
      </body>
    </html>
  `);
});

app.listen(3000);

Redoc CLI

# Install
npm install -g redoc-cli

# Generate static HTML
redoc-cli bundle openapi.yaml -o docs/index.html

# Serve with live reload
redoc-cli serve openapi.yaml --watch

# Custom options
redoc-cli bundle openapi.yaml \
  --output docs/index.html \
  --title "My API Documentation" \
  --options.theme.colors.primary.main="#2c3e50"

Stoplight Elements

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no" />
    <title>API Documentation</title>
    <script src="https://unpkg.com/@stoplight/elements/web-components.min.js"></script>
    <link rel="stylesheet" href="https://unpkg.com/@stoplight/elements/styles.min.css" />
  </head>
  <body>
    <elements-api
      apiDescriptionUrl="/openapi.yaml"
      router="hash"
      layout="sidebar"
    />
  </body>
</html>

Documentation from Code

JSDoc to OpenAPI

/**
 * @openapi
 * /api/users:
 *   get:
 *     summary: Get all users
 *     description: Retrieve a paginated list of all users
 *     tags:
 *       - Users
 *     parameters:
 *       - in: query
 *         name: page
 *         schema:
 *           type: integer
 *           minimum: 1
 *           default: 1
 *         description: Page number
 *       - in: query
 *         name: limit
 *         schema:
 *           type: integer
 *           minimum: 1
 *           maximum: 100
 *           default: 10
 *         description: Number of items per page
 *     responses:
 *       200:
 *         description: Successful response
 *         content:
 *           application/json:
 *             schema:
 *               type: object
 *               properties:
 *                 data:
 *                   type: array
 *                   items:
 *                     $ref: '#/components/schemas/User'
 *                 meta:
 *                   $ref: '#/components/schemas/PaginationMeta'
 *       401:
 *         $ref: '#/components/responses/UnauthorizedError'
 *     security:
 *       - bearerAuth: []
 */
router.get('/users', async (req, res) => {
  // Implementation
});

/**
 * @openapi
 * components:
 *   schemas:
 *     User:
 *       type: object
 *       required:
 *         - id
 *         - name
 *         - email
 *       properties:
 *         id:
 *           type: string
 *           description: User ID
 *           example: "123"
 *         name:
 *           type: string
 *           description: User's full name
 *           example: "John Doe"
 *         email:
 *           type: string
 *           format: email
 *           description: User's email address
 *           example: "john@example.com"
 */

TypeDoc (TypeScript)

/**
 * User management API
 * @module UserAPI
 */

/**
 * Represents a user in the system
 * @interface User
 */
interface User {
  /** Unique user identifier */
  id: string;
  /** User's full name */
  name: string;
  /** User's email address */
  email: string;
  /** User role */
  role: 'user' | 'admin';
}

/**
 * Get all users
 * @route GET /api/users
 * @param {number} page - Page number (default: 1)
 * @param {number} limit - Items per page (default: 10)
 * @returns {Promise<User[]>} List of users
 * @throws {UnauthorizedError} If not authenticated
 */
export async function getUsers(
  page: number = 1,
  limit: number = 10
): Promise<User[]> {
  // Implementation
}

/**
 * Create a new user
 * @route POST /api/users
 * @param {CreateUserRequest} data - User data
 * @returns {Promise<User>} Created user
 * @throws {ValidationError} If data is invalid
 * @throws {ConflictError} If email already exists
 */
export async function createUser(data: CreateUserRequest): Promise<User> {
  // Implementation
}

Python Docstrings (FastAPI)

from fastapi import FastAPI, HTTPException
from pydantic import BaseModel
from typing import List, Optional

app = FastAPI(
    title="User Management API",
    description="API for managing users and authentication",
    version="1.0.0",
    docs_url="/docs",
    redoc_url="/redoc"
)

class User(BaseModel):
    """
    User model representing a user account.

    Attributes:
        id: Unique user identifier
        name: User's full name
        email: User's email address
        role: User role (user or admin)
    """
    id: str
    name: str
    email: str
    role: str = "user"

@app.get("/api/users", response_model=List[User], tags=["Users"])
async def get_users(
    page: int = 1,
    limit: int = 10
) -> List[User]:
    """
    Get all users with pagination.

    Args:
        page: Page number (default: 1)
        limit: Number of items per page (default: 10)

    Returns:
        List of users

    Raises:
        HTTPException: If unauthorized (401)
    """
    # Implementation
    return []

@app.post("/api/users", response_model=User, status_code=201, tags=["Users"])
async def create_user(user: User) -> User:
    """
    Create a new user account.

    Args:
        user: User data including name, email, and optional role

    Returns:
        Created user object

    Raises:
        HTTPException: If validation fails (400)
        HTTPException: If email already exists (409)
    """
    # Implementation
    return user

Documentation Templates

Markdown API Reference

# API Reference

Base URL: `https://api.example.com/v1`

## Authentication

All API requests require authentication using a Bearer token:

```bash
Authorization: Bearer YOUR_ACCESS_TOKEN

Get your access token by calling the /auth/login endpoint.

Endpoints

Users

Get All Users

GET /api/users

Retrieve a paginated list of users.

Parameters

Response

{
  "data": [
    {
      "id": "123",
      "name": "John Doe",
      "email": "john@example.com",
      "role": "user"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 10,
    "total": 42,
    "totalPages": 5
  }
}

Status Codes

• 200 OK - Success
• 401 Unauthorized - Missing or invalid authentication
• 500 Internal Server Error - Server error

Example Request

curl -X GET "https://api.example.com/v1/api/users?page=1&limit=10" \
  -H "Authorization: Bearer YOUR_TOKEN"

const response = await fetch('https://api.example.com/v1/api/users?page=1&limit=10', {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN'
  }
});
const data = await response.json();

import requests

response = requests.get(
    'https://api.example.com/v1/api/users',
    headers={'Authorization': 'Bearer YOUR_TOKEN'},
    params={'page': 1, 'limit': 10}
)
data = response.json()

Create User

POST /api/users

Create a new user account.

Request Body

{
  "name": "John Doe",
  "email": "john@example.com",
  "password": "SecurePass123!",
  "role": "user"
}

Response

{
  "id": "123",
  "name": "John Doe",
  "email": "john@example.com",
  "role": "user",
  "createdAt": "2024-01-15T10:30:00Z"
}

Status Codes

• 201 Created - User created successfully
• 400 Bad Request - Invalid request data
• 409 Conflict - Email already exists
• 401 Unauthorized - Authentication required

Error Handling

All errors follow a consistent format:

{
  "code": "ERROR_CODE",
  "message": "Human-readable error message",
  "details": {
    "field": "Additional error details"
  }
}

Common Error Codes

Rate Limiting

API requests are limited to:

• 100 requests per minute for authenticated users
• 20 requests per minute for unauthenticated requests

Rate limit headers are included in all responses:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1610000000

Pagination

All list endpoints support pagination with these parameters:

• page - Page number (default: 1)
• limit - Items per page (default: 10, max: 100)

Responses include pagination metadata:

{
  "data": [...],
  "meta": {
    "page": 1,
    "limit": 10,
    "total": 100,
    "totalPages": 10
  }
}

Versioning

The API uses URL versioning:

• Current version: v1
• Base URL: https://api.example.com/v1

Breaking changes will be introduced in new versions (v2, v3, etc.)

### Getting Started Guide

```markdown
# Getting Started

This guide will help you make your first API request.

## 1. Get Your API Key

Sign up at [https://example.com/signup](https://example.com/signup) to get your API key.

## 2. Make Your First Request

### Using curl

```bash
curl -X GET https://api.example.com/v1/api/users \
  -H "Authorization: Bearer YOUR_API_KEY"

Using JavaScript

const response = await fetch('https://api.example.com/v1/api/users', {
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
});

const users = await response.json();
console.log(users);

Using Python

import requests

response = requests.get(
    'https://api.example.com/v1/api/users',
    headers={'Authorization': 'Bearer YOUR_API_KEY'}
)

users = response.json()
print(users)

3. Create a Resource

curl -X POST https://api.example.com/v1/api/users \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John Doe",
    "email": "john@example.com"
  }'

4. Handle Errors

Always check the response status:

try {
  const response = await fetch('https://api.example.com/v1/api/users', {
    headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
  });

  if (!response.ok) {
    const error = await response.json();
    console.error('Error:', error.message);
    return;
  }

  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error('Network error:', error);
}

Next Steps

• Read the API Reference
• Explore code examples
• Check out best practices
• Join our developer community

## Documentation Generation Tools

### Docusaurus (Facebook)

```bash
# Create new site
npx create-docusaurus@latest my-docs classic

# Install OpenAPI plugin
npm install docusaurus-plugin-openapi-docs

# Configure
# docusaurus.config.js
module.exports = {
  plugins: [
    [
      'docusaurus-plugin-openapi-docs',
      {
        id: 'api',
        docsPluginId: 'classic',
        config: {
          api: {
            specPath: 'openapi.yaml',
            outputDir: 'docs/api',
            sidebarOptions: {
              groupPathsBy: 'tag'
            }
          }
        }
      }
    ]
  ]
};

# Generate docs
npm run docusaurus gen-api-docs all

# Serve
npm run start

Slate (Beautiful API Docs)

# Clone template
git clone https://github.com/slatedocs/slate.git my-api-docs
cd my-api-docs

# Install dependencies
bundle install

# Edit source/index.html.md
# Run server
bundle exec middleman server

# Build static site
bundle exec middleman build

ReadMe.io

# Install CLI
npm install -g rdme

# Upload OpenAPI spec
rdme openapi openapi.yaml --key YOUR_README_API_KEY

# Sync with GitHub
rdme openapi openapi.yaml --github --key YOUR_README_API_KEY

MkDocs (Python)

# Install
pip install mkdocs mkdocs-material

# Create new project
mkdocs new my-api-docs
cd my-api-docs

# Configure mkdocs.yml
site_name: My API Documentation
theme:
  name: material
  features:
    - navigation.tabs
    - navigation.sections
    - toc.integrate

nav:
  - Home: index.md
  - Getting Started: getting-started.md
  - API Reference: api-reference.md
  - Examples: examples.md

# Serve locally
mkdocs serve

# Build
mkdocs build

Code Examples Generator

Automatic Code Generation

// From OpenAPI spec
const CodeGen = require('openapi-client-axios-typegen');

async function generateSDK() {
  const api = await CodeGen.generateClient('openapi.yaml');

  // Generated TypeScript client
  const users = await api.getUsers({ page: 1, limit: 10 });
  const newUser = await api.createUser({
    name: 'John Doe',
    email: 'john@example.com'
  });
}

Multi-Language Examples

// examples-generator.js
const examples = {
  getUsersCurl: `curl -X GET "https://api.example.com/v1/api/users?page=1&limit=10" \\
  -H "Authorization: Bearer YOUR_TOKEN"`,

  getUsersJavaScript: `const response = await fetch('https://api.example.com/v1/api/users?page=1&limit=10', {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN'
  }
});
const data = await response.json();`,

  getUsersPython: `import requests

response = requests.get(
    'https://api.example.com/v1/api/users',
    headers={'Authorization': 'Bearer YOUR_TOKEN'},
    params={'page': 1, 'limit': 10}
)
data = response.json()`,

  getUsersGo: `client := &http.Client{}
req, _ := http.NewRequest("GET", "https://api.example.com/v1/api/users?page=1&limit=10", nil)
req.Header.Add("Authorization", "Bearer YOUR_TOKEN")
resp, _ := client.Do(req)`,

  getUsersRuby: `require 'net/http'

uri = URI('https://api.example.com/v1/api/users?page=1&limit=10')
req = Net::HTTP::Get.new(uri)
req['Authorization'] = 'Bearer YOUR_TOKEN'
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }`
};

Best Practices

Documentation Content

• Write clear, concise descriptions
• Include code examples in multiple languages
• Provide real-world use cases
• Document all error codes
• Include rate limits and quotas
• Show authentication examples
• Explain pagination
• Document versioning strategy

Interactive Features

• Add "Try it out" functionality
• Include request/response examples
• Show syntax highlighting
• Provide copy-to-clipboard buttons
• Add search functionality
• Include navigation menu

Maintenance

• Keep docs synchronized with code
• Automate documentation generation
• Version documentation with API
• Review and update regularly
• Test all code examples
• Collect user feedback

SEO and Discovery

• Use descriptive titles
• Add meta descriptions
• Create sitemap
• Use proper heading structure
• Include keywords
• Make docs publicly accessible

Notes

• Auto-generate docs from OpenAPI specs when possible
• Include interactive API explorers
• Provide examples in multiple programming languages
• Keep documentation up-to-date with code changes
• Use version control for documentation
• Make documentation searchable
• Include getting started guides
• Document authentication thoroughly
• Show error handling examples
• Test all code examples before publishing
• Collect and incorporate user feedback
• Use consistent formatting and style

Converted and distributed by TomeVault — claim your Tome and manage your conversions.