Metadata-Version: 2.4
Name: swagger-diff-ui
Version: 0.1.0
Summary: Drop-in Swagger UI with OpenAPI schema diff (branch/commit baseline)
Author: swagger-diff-ui contributors
License: MIT
Project-URL: Homepage, https://github.com/Iman-Sharei/swagger-diff-ui
Project-URL: Repository, https://github.com/Iman-Sharei/swagger-diff-ui
Project-URL: Issues, https://github.com/Iman-Sharei/swagger-diff-ui/issues
Keywords: openapi,swagger,django,drf,diff,drf-spectacular
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Web Environment
Classifier: Framework :: Django
Classifier: Framework :: Django :: 4.2
Classifier: Framework :: Django :: 5.0
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Documentation
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: Django>=4.2
Requires-Dist: djangorestframework>=3.14
Requires-Dist: drf-spectacular>=0.27
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Requires-Dist: pytest-django>=4; extra == "dev"
Dynamic: license-file

# 🔀 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.

![Schema diff UI showing NEW, UPDATE, and DELETE badges on Swagger endpoints](docs/assets/schema-diff-preview.png)

*Pick a baseline → Compare → see what changed.*

---

## ✨ What you get

| | Feature | What it does |
|---|---------|----------------|
| 🌿 | **Branch / commit** selectors | Baseline from your real git history |
| ▶️ | **Compare** | Diff current schema vs that baseline |
| 🟢🟡🔴 | **NEW / UPDATE / DELETE** tags | On the left of every changed operation |
| 🎯 | **Changed only** | Hide unchanged APIs (toggle anytime) |
| 🔬 | **Field-level UPDATE** | Params, body, responses, schema props — colored dots |

> ⚙️ Baseline export uses a temporary **git worktree** + `manage.py spectacular`. Intended for **local / DEBUG** only.

---

## 📦 Requirements

- Python **3.10+**
- Django **4.2+**
- Django REST Framework
- [drf-spectacular](https://drf-spectacular.readthedocs.io/)
- A **git checkout** of your project (for branch/commit baselines)

---

## 🚀 Install

### From GitHub

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

### From PyPI *(when published)*

```bash
pip install swagger-diff-ui
```

### Local editable

```bash
pip install -e ".[dev]"
```

---

## 🔌 Wire into Django

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

### 1️⃣ Add the app

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

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

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

urlpatterns = [
    # Real OpenAPI document (unchanged)
    path("api/schema/", SpectacularAPIView.as_view(), name="api-schema"),

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

### 3️⃣ Open the docs

```text
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 ▾**

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

---

## 🗺️ Routes

Assuming you included under `api/`:

| URL | Role |
|-----|------|
| `/api/docs/` | Swagger UI + schema-diff drawer |
| `/api/schema/` | Your real OpenAPI schema (**spectacular**) |
| `/api/swagger-diff/git-refs/` | Branches + recent commits |
| `/api/swagger-diff/diff/?ref=…` | Diff report vs baseline |
| `/api/swagger-diff/baseline/?ref=…` | Raw baseline OpenAPI (optional) |

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

---

## 🔒 Safety notes

- Git baseline APIs are gated to **`DJANGO_ENV == "local"`** or **`DEBUG=True`**
- Do **not** expose these on production with `DEBUG=True`
- Prefer wiring `swagger_diff_ui` only in local / staging settings

---

## 🧪 Develop & test

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

---

## 📄 License

[MIT](LICENSE) · made for Django + DRF teams who live in `/api/docs/`
