api-docs-generator

Generates API documentation from code including OpenAPI specs, JSDoc, and Python docstrings. Use when documenting APIs, REST endpoints, or library functions.

⭐19stars🔀4forks📁View on GitHub🕐Updated Dec 2, 2025⬇️1downloads

When & Why to Use This Skill

This Claude skill automates the generation of professional API documentation directly from source code, supporting industry standards like OpenAPI (Swagger), JSDoc, and Python docstrings. It helps developers maintain accurate, up-to-date technical references for REST endpoints and library functions, significantly reducing manual documentation overhead and improving developer experience.

Use Cases

  • Interactive API Reference: Automatically generate OpenAPI specifications from web framework routes (e.g., Express.js) to provide frontend teams with interactive Swagger UI documentation.
  • Library Documentation: Convert JSDoc comments or Python docstrings into searchable HTML documentation for JavaScript or Python libraries, making it easier for users to understand function signatures and usage.
  • Documentation-as-Code: Integrate documentation extraction into the development workflow to ensure that technical docs stay in sync with code changes, preventing outdated or misleading information.
  • Technical Onboarding: Create structured API guides and endpoint references to accelerate the onboarding process for new developers and improve internal knowledge sharing.
nameapi-docs-generator
descriptionGenerates 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