← Back to all products
$19
API Documentation Toolkit
Swagger/OpenAPI generators, Redoc themes, API changelog automation, and developer portal templates.
PythonYAMLMarkdownJSON
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 SampleFile Structure 25 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
├── interactive.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-pytest-9.0.2.pyc
│ └── 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 ...