api-docs-generator

name	api-docs-generator
description	Generates API documentation from code including OpenAPI specs, JSDoc, and Python docstrings. Use when documenting APIs, REST endpoints, or library functions.

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/

Step 4: Organize Output

Structure documentation:

docs/
├── api/
│   ├── openapi.json       # OpenAPI specification
│   ├── index.html         # Interactive API docs
│   └── endpoints/         # Endpoint details
├── reference/
│   ├── classes/           # Class documentation
│   ├── functions/         # Function documentation
│   └── types/             # Type definitions
└── guides/
    ├── authentication.md  # Auth guide
    └── examples.md        # Usage examples

Step 5: Add Examples

Include practical examples:

## Authentication

All API requests require authentication:

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

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

\`\`\`python
import requests

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

OpenAPI Specification

Basic Structure

openapi: 3.0.0
info:
  title: My API
  version: 1.0.0
  description: API description

servers:
  - url: https://api.example.com/v1

paths:
  /users:
    get:
      summary: List users
      parameters:
        - name: page
          in: query
          schema:
            type: integer
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'

components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string

Documentation Checklist

• All endpoints documented
• Request/response examples included
• Authentication explained
• Error codes documented
• Rate limiting described
• Code examples in multiple languages
• Interactive API explorer available