← Back to all products

API Documentation Toolkit

$19

Swagger/OpenAPI generators, Redoc themes, API changelog automation, and developer portal templates.

📁 22 files

MarkdownYAMLPython

📄 Product Preview

Try the interactive reader and demo tools below, or get the full product with all content unlocked.

📖 Interactive Reader (Free Preview) ⚙ Try Demo Tools 📦 Download Free Sample

📁 File Structure 22 files

api-documentation-toolkit/ ├── LICENSE ├── README.md ├── docs/ │ ├── QUICKSTART.md │ └── how-the-generators-work.md ├── examples/ │ ├── sample-openapi.yaml │ └── two-versioned-specs/ │ ├── v1.yaml │ └── v2.yaml ├── free-sample.zip ├── guide/ │ ├── 01_what-s-inside.md │ ├── 02_quick-start.md │ ├── 03_configuration.md │ └── 04_faq.md ├── index.html ├── src/ │ ├── __pycache__/ │ │ └── changelog_gen.cpython-312.pyc │ ├── changelog_gen.py │ ├── openapi_from_code.py │ └── portal_build.py ├── templates/ │ ├── changelog-template.md │ ├── developer-portal.html │ └── redoc-theme.css └── tests/ ├── __pycache__/ │ └── test_changelog_gen.cpython-312.pyc └── test_changelog_gen.py

📖 Documentation Preview README excerpt

API Documentation Toolkit

A collection of Python tools for generating, maintaining, and publishing API documentation. Includes an OpenAPI spec generator that extracts route metadata from annotated Python handlers, a changelog generator that diffs two OpenAPI specs and produces markdown, and a static developer portal builder -- all using the Python standard library only.

What's Inside

Directory	Contents
`src/`	Three runnable Python tools: OpenAPI generator, changelog differ, portal builder
`templates/`	Developer portal HTML template, Redoc CSS theme, changelog markdown template
`examples/`	Sample OpenAPI spec + two versioned specs for testing the changelog differ
`docs/`	Quick start guide + detailed explanation of how the generators work
`tests/`	Unit tests for the changelog generator (stdlib `unittest`)

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

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



*... continues with setup instructions, usage examples, and more.*

📄 Code Sample .py preview

src/changelog_gen.py """Diff two OpenAPI specs and generate a markdown changelog. Compares an old and new OpenAPI YAML specification and produces a structured markdown changelog documenting added endpoints, removed endpoints, modified schemas, parameter changes, and breaking changes. Uses only the Python standard library -- no external dependencies. Usage: python3 changelog_gen.py old_spec.yaml new_spec.yaml python3 changelog_gen.py old_spec.yaml new_spec.yaml --output CHANGELOG.md python3 changelog_gen.py old_spec.yaml new_spec.yaml --version 2.0.0 """ from __future__ import annotations import argparse import logging import sys from dataclasses import dataclass, field from datetime import date from pathlib import Path from typing import Any logger = logging.getLogger(__name__) # --------------------------------------------------------------------------- # Minimal YAML parser (stdlib only) # --------------------------------------------------------------------------- # Handles the subset of YAML commonly found in OpenAPI specs: # - Mappings (key: value) # - Sequences (- item) # - Quoted and unquoted scalars # - Multi-line values with indentation # - Comments (#) # Does NOT handle: anchors/aliases, flow mappings, tags, multi-document def parse_yaml(text: str) -> dict[str, Any]: """Parse a YAML string into a Python dictionary. This is a simplified parser for OpenAPI-style YAML files. It handles nested mappings, sequences, and scalar values. For production use with complex YAML, consider using a full YAML library. Args: text: YAML-formatted string. Returns: # ... 632 more lines ...

Buy Now — $19 Back to Products