← Back to all products

API Documentation Toolkit

$19

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

25 files
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 Sample

File 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

DirectoryContents
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 ...