What's Inside

This chapter covers the core features and capabilities of API Documentation Toolkit.

What's Inside

Features

• OpenAPI from Code -- Extract route metadata from annotated Python handler functions and generate a valid OpenAPI 3.1 skeleton. No framework dependency -- works with any Python codebase that uses decorators or docstrings.
• Changelog Generator -- Diff two OpenAPI YAML specs (v1 vs v2) and emit a structured markdown changelog listing added endpoints, removed endpoints, modified schemas, and breaking changes.
• Developer Portal Builder -- Render a self-contained static HTML developer portal from an OpenAPI spec file. Includes navigation, endpoint listing, schema documentation, and a clean responsive theme.
• Redoc Theme -- A custom CSS theme for Redoc-based API documentation portals.
• Changelog Template -- A markdown template for API changelog entries with sections for added, changed, deprecated, removed, fixed, and security updates.

Quick Start

Follow this guide to get API Documentation Toolkit up and running in your environment.

Quick Start

1. Generate an OpenAPI Spec from Python Code

# Run the generator on a sample handler file
python3 src/openapi_from_code.py

# Or import and use in your own script
python3 -c "
from src.openapi_from_code import OpenAPIGenerator
gen = OpenAPIGenerator(title='My API', version='1.0.0')
gen.add_route('GET', '/users', summary='List users', tags=['Users'])
print(gen.to_yaml())
"

2. Generate a Changelog from Two Spec Versions

# Diff the included v1 and v2 sample specs
python3 src/changelog_gen.py examples/two-versioned-specs/v1.yaml examples/two-versioned-specs/v2.yaml

# Output is a structured markdown changelog

3. Build a Static Developer Portal

# Generate a developer portal from an OpenAPI spec
python3 src/portal_build.py examples/sample-openapi.yaml --output portal.html

# Open portal.html in your browser

File Inventory

api-documentation-toolkit/
├── README.md                                # This file
├── LICENSE                                  # MIT License
├── src/
│   ├── openapi_from_code.py                 # Generate OpenAPI from annotated Python handlers
│   ├── changelog_gen.py                     # Diff two OpenAPI specs -> markdown changelog
│   └── portal_build.py                      # Build static HTML developer portal
├── templates/
│   ├── developer-portal.html                # HTML template with CSS for the portal
│   ├── redoc-theme.css                      # Custom Redoc CSS theme
│   └── changelog-template.md                # Markdown template for API changelogs
├── examples/
│   ├── sample-openapi.yaml                  # Sample OpenAPI spec for portal demo
│   └── two-versioned-specs/
│       ├── v1.yaml                          # Version 1 spec (for changelog diff)
│       └── v2.yaml                          # Version 2 spec (for changelog diff)
├── docs/
│   ├── QUICKSTART.md                        # Step-by-step getting started guide
│   └── how-the-generators-work.md           # Technical deep-dive into the generators
└── tests/
    └── test_changelog_gen.py                # Tests for the changelog generator