🔀 swagger-diff-ui

Drop-in Swagger UI for Django + DRF that diffs your live OpenAPI schema against a git branch or commit — then paints every changed endpoint as NEW · UPDATE · DELETE.

No Node. No separate SPA. Same /api/docs/ you already open — with a small baseline drawer on top.

Pick a baseline → Compare → see what changed.

✨ What you get

⚙️ Baseline export uses a temporary git worktree + manage.py spectacular. HTTP endpoints are intended for local / DEBUG only; the management command is safe for CI.

📦 Requirements

• Python 3.10+
• Django 4.2+
• Django REST Framework
• drf-spectacular
• A git checkout of your project (for branch/commit baselines)

🚀 Install

pip install swagger-diff-ui

From GitHub

pip install "git+https://github.com/Iman-Sharei/swagger-diff-ui.git"

🔌 Wire into Django

Same idea as spectacular: one app + a few routes.

1️⃣ Add the app

# settings — typically local / debug only
INSTALLED_APPS = [
    # ...
    "drf_spectacular",
    "swagger_diff_ui",
]

2️⃣ Keep spectacular’s schema + include our URLs

# urls.py
from django.urls import include, path
from drf_spectacular.views import SpectacularAPIView

urlpatterns = [
    # Real OpenAPI document (unchanged)
    # ⚠️ URL name MUST be "api-schema" (or set SWAGGER_DIFF_SCHEMA_URL_NAME)
    path("api/schema/", SpectacularAPIView.as_view(), name="api-schema"),

    # Diff UI + helpers
    path("api/", include("swagger_diff_ui.urls")),
]

The Swagger view resolves the schema via Django’s URL name api-schema. If your project uses a different name, either rename it or set:

SWAGGER_DIFF_SCHEMA_URL_NAME = "my-schema"  # must match SpectacularAPIView's name=

3️⃣ Open the docs

http://127.0.0.1:8000/api/docs/

Done. ✅

🖱️ How to use

1. Open /api/docs/
2. In the dark drawer, pick a baseline branch or commit
3. Click Compare
4. Changed endpoints get NEW / UPDATE / DELETE
5. Open an UPDATE row for field-level diffs + colored Example Value dots
6. Use Changed only / Show all APIs and Hide ▴ / Show ▾

Git refs accept branch names, SHAs, and relative history forms such as HEAD~1, main~3, or HEAD^.

⏱️ First compare for a given SHA can take a bit (worktree + schema export). Results cache under .schema-cache/ — keep that folder in .gitignore.

🧱 CI / CLI (breaking changes)

Run inside your Django project (same env as manage.py):

# Diff current schema vs previous commit; fail CI if breaking
python manage.py swagger_diff --ref HEAD~1 --ci

# Machine-readable report
python manage.py swagger_diff --ref origin/main --format json

# Fail only when you ask
python manage.py swagger_diff --ref HEAD~1 --fail-on-breaking

Breaking detection is heuristic (removed operations/params/fields, newly required request fields, type/$ref changes, removed enum values, …). Use it as a CI gate, not a formal compatibility proof.

Example GitHub Actions step:

- name: OpenAPI breaking change check
  run: python manage.py swagger_diff --ref origin/${{ github.base_ref }} --ci

🗺️ Routes

Assuming you included under api/:

Diff helpers live under /api/swagger-diff/… so they never collide with /api/schema/.

⚙️ Settings & environment

If your Django settings live elsewhere (e.g. myproject.settings.dev), set DJANGO_SETTINGS_MODULE as usual — or set SWAGGER_DIFF_SETTINGS_MODULE when the baseline worktree should load a different module than the running process.

🔒 Safety notes

• Git baseline HTTP APIs are gated to DJANGO_ENV == "local" or DEBUG=True
• Helper endpoints also reject refs starting with -, pass refs after --end-of-options, and block cross-site browser calls (Sec-Fetch-Site / mismatched Origin)
• The swagger_diff management command skips the local-only gate so CI can run with DEBUG=False
• Do not expose the HTTP helpers on production with DEBUG=True
• Prefer wiring swagger_diff_ui only in local / staging settings (CLI can stay available wherever INSTALLED_APPS includes the package)

🧪 Develop & test

pip install -e ".[dev]"
pytest -q

CI runs the same tests on Python 3.10–3.12 (see .github/workflows/ci.yml).

Sample project

cd examples/sample_project
python manage.py runserver
# → http://127.0.0.1:8000/api/docs/

See examples/sample_project/README.md.

Release notes: CHANGELOG.md.

📄 License

MIT · made for Django + DRF teams who live in /api/docs/