api-docs-generator

API Documentation Generator

Quick Start

Generate API docs based on code type:

# OpenAPI from Express routes
npx swagger-jsdoc -d swaggerDef.js routes/*.js

# JSDoc for JavaScript
npx jsdoc src/ -d docs/

# Python docstrings
pdoc --html --output-dir docs/ mypackage/

Instructions

Step 1: Identify API Type

Determine documentation approach:

API Type	Tool	Output
REST API	OpenAPI/Swagger	Interactive API docs
GraphQL	GraphQL Schema	Schema documentation
JavaScript Library	JSDoc	HTML reference
Python Library	Sphinx/pdoc	HTML reference

Step 2: Extract Documentation

REST API (OpenAPI):

Scan route files for JSDoc comments:

/**
 * @swagger
 * /users:
 *   get:
 *     summary: Get all users
 *     responses:
 *       200:
 *         description: List of users
 */
router.get('/users', getUsers);

Generate spec:

npx swagger-jsdoc -d swaggerDef.js routes/*.js -o openapi.json

JavaScript Library (JSDoc):

/**
 * Adds two numbers together.
 * @param {number} a - First number
 * @param {number} b - Second number
 * @returns {number} Sum of a and b
 * @example
 * add(2, 3); // returns 5
 */
function add(a, b) {
  return a + b;
}

Python (Docstrings):

def add(a: int, b: int) -> int:
    """Add two numbers together.
    
    Args:
        a: First number
        b: Second number
        
    Returns:
        Sum of a and b
        
    Example:
        >>> add(2, 3)
        5
    """
    return a + b

Step 3: Generate Documentation

OpenAPI/Swagger:

# Generate OpenAPI spec
npx swagger-jsdoc -d swaggerDef.js routes/*.js -o openapi.json

# Serve interactive docs
npx swagger-ui-express openapi.json

JSDoc:

npx jsdoc src/ -d docs/ -r

Python Sphinx:

sphinx-apidoc -o docs/source mypackage/
cd docs && make html

Python pdoc:

pdoc --html --output-dir docs/ mypackage/