drf-spectacular-sidecar

drf-spectacular-sidecar is a companion package to drf-spectacular (though it has no hard dependency on it) that solves one narrow problem: serving the Swagger UI and Redoc JavaScript/CSS bundles from your own Django server instead of pulling them from a public CDN at request time. Once registered in INSTALLED_APPS, Django’s staticfiles machinery picks up the vendored bundles automatically, so runserver and collectstatic both work without any extra configuration.

The package itself contains almost no application code — a single AppConfig and a static/ directory holding pinned builds of swagger-ui-dist and redoc. The real engineering lives in the repository’s release automation: a monthly scheduled GitHub Action runs update.py, which checks jsdelivr for newer Swagger UI / Redoc releases, downloads and hash-validates the new bundles, bumps the package version to a date-based scheme (e.g. 2026.9.1), and publishes straight to PyPI. This gives self-hosted Django/DRF projects a reproducible, offline-friendly way to serve interactive API docs without depending on an external CDN being reachable or unchanged.

What You Get

• Pinned, self-contained builds of Swagger UI (swagger-ui-dist) and Redoc (redoc) shipped as package data, no CDN fetch required
• A Django AppConfig that plugs into INSTALLED_APPS so the bundles are picked up by both runserver and collectstatic automatically
• Predictable date-based version numbers (e.g. 2026.9.1) generated by an automated monthly release job, so you can pin an exact asset snapshot
• License files for both vendored projects included alongside the assets so provenance and licensing stay auditable
• Zero runtime dependency on drf-spectacular itself — usable standalone with any tool that wants local Swagger UI/Redoc assets

Common Use Cases

• Serving interactive OpenAPI documentation (Swagger UI or Redoc) from a Django/DRF backend without relying on a public CDN
• Air-gapped or offline deployments where projects can’t fetch third-party JavaScript from jsdelivr or unpkg at runtime
• Pinning an exact, reproducible Swagger UI/Redoc version across environments instead of tracking whatever a CDN happens to serve
• Simplifying drf-spectacular’s schema-viewer setup by handing it a static-asset source that’s already wired into Django’s staticfiles config

Under The Hood

Architecture The installable package (drf_spectacular_sidecar/) is deliberately thin: a single AppConfig in apps.py registers the app with Django, and everything else is static payload under static/drf_spectacular_sidecar/ — pre-built Swagger UI and Redoc bundles plus their upstream LICENSE files. There are no views, models, URLs, or business logic to speak of; the app’s entire contract is “be discoverable by Django’s staticfiles finder.” The actual engineering — checking jsdelivr for new releases, downloading and SHA-256-validating assets, bumping distributions.json/config.json, and cutting a dated release — lives in root-level scripts (update.py, update_assets.py) that run only in CI, entirely outside the shipped package.

Tech Stack Pure Python, targeting Django >= 2.2 as its sole runtime dependency (declared in requirements/base.txt). Packaging uses classic setuptools/setup.py rather than a pyproject.toml-based build backend, with twine, wheel, and packaging reserved for the release tooling. Vendored front-end assets (Swagger UI, Redoc) are sourced from npm via the jsdelivr CDN’s metadata and content APIs, not from a JS package manager directly. Distribution is a standard PyPI upload triggered from a GitHub Actions workflow (update.yml) on a monthly cron plus manual workflow_dispatch.

Code Quality No test suite or test-oriented CI job exists in the repository — the only workflow present runs the monthly asset-update/publish job, not tests. Given the package’s near-zero runtime logic (one AppConfig class, one version string), the risk surface this leaves untested is small, and the code that does exist is short, conventionally named, and easy to read at a glance. There’s a py.typed marker signaling PEP 561 type-checking support, but no linter or formatter configuration (no flake8/ruff/black config files) is present to enforce style automatically.

What Makes It Unique The interesting design decision isn’t in the shipped package at all — it’s the self-publishing release loop. Rather than requiring a human to notice new Swagger UI/Redoc releases, the repository checks jsdelivr on a schedule, validates downloaded assets by hash before accepting them, and only cuts a new dated PyPI release when something actually changed (or a hotfix flag is set). That turns a routine dependency-vendoring chore into a fully automated, auditable pipeline, letting downstream Django projects consume a versioned artifact instead of scripting their own CDN-fetch step.