DEV Community

Thesius Code
Thesius Code

Posted on • Originally published at datanest-stores.pages.dev

API Documentation Toolkit

#python #api #rest #webdev

API Documentation Toolkit

Stop shipping APIs with afterthought documentation. This toolkit gives you production-ready OpenAPI spec generators, customizable Redoc themes, automated changelog pipelines, and developer portal templates that make your API a pleasure to integrate with. Whether you're documenting a 5-endpoint microservice or a 200-endpoint platform, these tools scale with you and enforce consistency across teams.

Key Features

  • OpenAPI 3.1 Spec Generator — Python-based generator that introspects your route definitions and produces valid OpenAPI YAML with schemas, examples, and security definitions
  • Redoc Theme Engine — Four pre-built themes (corporate, developer, minimal, dark) with CSS variable customization and logo injection
  • Changelog Automation — Git-diff-based changelog generator that detects breaking changes, new endpoints, and deprecations between spec versions
  • Developer Portal Templates — Static HTML/CSS portal with search, code samples in 5 languages, and authentication playground
  • Schema Validation Pipeline — Pre-commit hooks and CI scripts that validate your OpenAPI spec against the official JSON Schema
  • Multi-Format Export — Generate Markdown, HTML, and PDF documentation from a single OpenAPI source
  • Interactive Examples — Embedded Try It panels with configurable base URLs and auth token injection

Quick Start

  1. Extract the archive and review the project structure
  2. Point the generator at your API framework: 
# src/api_documentation_toolkit/core.py
from api_documentation_toolkit import SpecGenerator

generator = SpecGenerator(
    title="Acme Corp API",
    version="2.1.0",
    base_url="https://api.example.com/v2",
    auth_type="bearer"
)

# Register your routes (or auto-discover from FastAPI/Flask)
generator.add_endpoint(
    method="GET",
    path="/users/{user_id}",
    summary="Retrieve a user by ID",
    response_model="UserResponse",
    tags=["Users"]
)

# Generate the spec
generator.export("openapi.yaml", format="yaml")
Enter fullscreen mode Exit fullscreen mode
  1. Build the portal: 
python -m api_documentation_toolkit.portal \
    --spec openapi.yaml \
    --theme dark \
    --output ./docs-site
Enter fullscreen mode Exit fullscreen mode

Architecture 

api-documentation-toolkit/
├── src/
│   ├── core.py              # SpecGenerator — builds OpenAPI from route defs
│   ├── changelog.py         # Diff engine — compares two spec versions
│   ├── portal_builder.py    # Static site generator for dev portal
│   ├── themes/              # Redoc CSS themes and layout templates
│   └── validators.py        # Schema validation against OpenAPI 3.1
├── examples/
│   ├── fastapi_integration.py
│   ├── flask_integration.py
│   └── sample_spec.yaml
├── templates/
│   ├── portal/              # HTML templates for developer portal
│   └── changelog.md.j2      # Changelog Markdown template
└── config.example.yaml
Enter fullscreen mode Exit fullscreen mode

The generator works in three phases: Discover (scan routes or parse existing spec), Enrich (add examples, descriptions, security schemes), and Export (write to YAML/JSON and optionally build the portal).

Usage Examples

Generate a Changelog Between Versions 

from api_documentation_toolkit.changelog import ChangelogGenerator

changelog = ChangelogGenerator(
    old_spec="specs/v2.0.0.yaml",
    new_spec="specs/v2.1.0.yaml"
)

report = changelog.generate()
# report.breaking_changes -> [{"path": "/users", "change": "removed query param 'legacy_id'"}]
# report.new_endpoints -> [{"method": "POST", "path": "/users/bulk"}]
# report.deprecations -> [{"path": "/users/search", "sunset": "2026-06-01"}]

changelog.export("CHANGELOG.md", format="markdown")
Enter fullscreen mode Exit fullscreen mode

Validate a Spec in CI 

# .github/workflows/docs-validate.yml
- name: Validate OpenAPI Spec
  run: |
    python -m api_documentation_toolkit.validators \
        --spec openapi.yaml \
        --strict \
        --fail-on-warning
Enter fullscreen mode Exit fullscreen mode

Apply a Custom Redoc Theme 

# config.example.yaml
portal:
  theme: dark
  logo: "./assets/logo.svg"
  colors:
    primary: "#4A90D9"
    sidebar_bg: "#1a1a2e"
    text: "#e0e0e0"
  typography:
    heading_font: "Inter"
    code_font: "JetBrains Mono"
  features:
    try_it_enabled: true
    code_samples: [python, javascript, curl, go, ruby]
Enter fullscreen mode Exit fullscreen mode

Configuration

Key Type Default Description
spec.title string required API title in generated spec
spec.version string required Semantic version of the API
spec.base_url string required Production base URL
spec.auth_type string "bearer" Auth scheme: bearer, apikey, oauth2
portal.theme string "minimal" Redoc theme name
portal.try_it_enabled bool true Enable interactive request panel
changelog.detect_breaking bool true Flag breaking changes in diff
export.formats list ["yaml"] Output formats: yaml, json, html

Best Practices

  • Version your specs in git. Store each release as specs/v{version}.yaml so the changelog generator can diff between any two versions.
  • Generate, don't hand-write. Use the SpecGenerator with your framework's route definitions as the source of truth — hand-written specs drift from reality.
  • Run validation in CI. Add the --strict flag to catch missing descriptions, empty examples, and undocumented error responses before they reach production.
  • Ship code samples in multiple languages. The portal builder generates samples from your spec's examples field — invest time in realistic request/response examples.
  • Use the sunset header. When deprecating endpoints, set x-sunset in your spec so the changelog generator surfaces the timeline.

Troubleshooting

Spec validation fails with "invalid reference"
Check that all $ref paths use the correct relative format (#/components/schemas/User, not ./schemas/User). The validator follows OpenAPI 3.1 reference resolution rules.

Portal build produces blank pages
Ensure your spec file is valid YAML/JSON before building. Run python -m api_documentation_toolkit.validators --spec your_spec.yaml first. Common cause: tabs instead of spaces in YAML.

Changelog shows no changes between versions
The diff engine compares normalized specs. If you only changed formatting or comment order, those are ignored by design. Verify actual structural changes exist between the two files.

Theme colors not applying
CSS variable overrides require the portal.theme key to be set to a valid base theme. Custom colors are applied on top of the base — setting colors without a base theme has no effect.

This is 1 of 7 resources in the API Developer Pro toolkit. Get the complete [API Documentation Toolkit] with all files, templates, and documentation for $19.

Get the Full Kit →

Or grab the entire API Developer Pro bundle (7 products) for $79 — save 30%.

Get the Complete Bundle →

Related Articles

Top comments (0)