Metadata-Version: 2.4
Name: coolswagger
Version: 0.1.2
Summary: Beautiful Swagger UI for FastAPI — dark/light theme + Monaco Editor
Project-URL: Homepage, https://github.com/SasquatchMe/coolswagger
Project-URL: Repository, https://github.com/SasquatchMe/coolswagger
Project-URL: Bug Tracker, https://github.com/SasquatchMe/coolswagger/issues
License: MIT
Keywords: dark-mode,docs,fastapi,monaco,openapi,swagger
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: FastAPI
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: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: fastapi>=0.100.0
Provides-Extra: dev
Requires-Dist: black; extra == 'dev'
Requires-Dist: build; extra == 'dev'
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: uvicorn[standard]; extra == 'dev'
Description-Content-Type: text/markdown

<div align="center">

```
  ██████╗ ██████╗  ██████╗ ██╗      ███████╗██╗    ██╗ █████╗  ██████╗  ██████╗ ███████╗██████╗
 ██╔════╝██╔═══██╗██╔═══██╗██║      ██╔════╝██║    ██║██╔══██╗██╔════╝ ██╔════╝ ██╔════╝██╔══██╗
 ██║     ██║   ██║██║   ██║██║      ███████╗██║ █╗ ██║███████║██║  ███╗██║  ███╗█████╗  ██████╔╝
 ██║     ██║   ██║██║   ██║██║      ╚════██║██║███╗██║██╔══██║██║   ██║██║   ██║██╔══╝  ██╔══██╗
 ╚██████╗╚██████╔╝╚██████╔╝███████╗ ███████║╚███╔███╔╝██║  ██║╚██████╔╝╚██████╔╝███████╗██║  ██║
  ╚═════╝ ╚═════╝  ╚═════╝ ╚══════╝ ╚══════╝ ╚══╝╚══╝ ╚═╝  ╚═╝ ╚═════╝  ╚═════╝ ╚══════╝╚═╝  ╚═╝
```

**Beautiful Swagger UI for FastAPI — dark mode, Monaco Editor, zero config**

[![PyPI version](https://img.shields.io/pypi/v/coolswagger?color=blue&style=flat-square)](https://pypi.org/project/coolswagger/)
[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue?style=flat-square)](https://www.python.org/)
[![License: MIT](https://img.shields.io/badge/license-MIT-green?style=flat-square)](LICENSE)
[![Downloads](https://img.shields.io/pypi/dm/coolswagger?style=flat-square)](https://pypi.org/project/coolswagger/)
[![FastAPI](https://img.shields.io/badge/FastAPI-0.100%2B-009688?style=flat-square&logo=fastapi)](https://fastapi.tiangolo.com/)

*Tired of FastAPI's plain white Swagger UI? One line and you get a proper dark mode, VS Code's Monaco Editor for request bodies, and theme persistence — no extra dependencies.*

</div>

---

## ✨ What you get

| | Default FastAPI Swagger UI | coolswagger |
|---|:---:|:---:|
| 🌙 Dark / ☀️ Light theme toggle | ✗ | ✓ |
| 💾 Theme saved across page reloads | ✗ | ✓ |
| 🖊️ Monaco Editor for request body (syntax highlight, bracket match) | ✗ | ✓ |
| 🔐 OAuth2 / `initOAuth` support | ✓ | ✓ |
| 🎛️ `swagger_ui_parameters` passthrough | ✓ | ✓ |
| 🎨 Custom CDN URLs | partial | ✓ |
| ⚡ Zero extra runtime dependencies | ✓ | ✓ |

---

## 📦 Installation

```bash
# pip
pip install coolswagger

# uv  (recommended)
uv add coolswagger

# poetry
poetry add coolswagger
```

Requires Python 3.10+ and FastAPI 0.100+.

---

## 🚀 Quick start

Replace the built-in FastAPI docs with a two-line change:

```python
from fastapi import FastAPI
from coolswagger import coolswagger_router

# disable the default /docs
app = FastAPI(docs_url=None, title="My API")

app.include_router(
    coolswagger_router(docs_url="/docs", title=app.title)
)
```

Open `/docs` — dark mode toggle is in the top-right corner, request body fields are Monaco editors.

---

## ⚙️ Advanced usage

### SwaggerConfig helper

```python
from fastapi import FastAPI
from coolswagger import SwaggerConfig, setup_swagger

app = FastAPI(docs_url=None, title="My API")

setup_swagger(app, SwaggerConfig(
    title=app.title,
    docs_url="/docs",
    coolswagger_enable=True,   # False → falls back to default Swagger UI
))
```

### OAuth2

```python
app.include_router(
    coolswagger_router(
        docs_url="/docs",
        title=app.title,
        oauth2_redirect_url="/oauth2-redirect",
        init_oauth={"clientId": "my-client", "scopes": "openid profile"},
    )
)
```

### Custom Swagger UI parameters

```python
app.include_router(
    coolswagger_router(
        docs_url="/docs",
        title=app.title,
        swagger_ui_parameters={
            "persistAuthorization": True,
            "filter": True,
            "syntaxHighlight.theme": "monokai",
        },
    )
)
```

### Self-hosted / offline (no CDN)

```python
app.include_router(
    coolswagger_router(
        docs_url="/docs",
        title=app.title,
        swagger_js_url="/static/swagger-ui-bundle.js",
        swagger_css_url="/static/swagger-ui.css",
        monaco_js_url="/static/monaco/vs/loader.js",
    )
)
```

---

## 📋 Parameters

| Parameter | Type | Default | Description |
|---|---|---|---|
| `title` | `str` | **required** | API title shown in the page |
| `docs_url` | `str` | `"/docs"` | URL path for the docs page |
| `openapi_url` | `str` | `"/openapi.json"` | URL to the OpenAPI schema |
| `swagger_js_url` | `str` | jsDelivr CDN | Swagger UI bundle JS |
| `swagger_css_url` | `str` | jsDelivr CDN | Swagger UI CSS |
| `swagger_favicon_url` | `str` | FastAPI favicon | Browser tab icon |
| `monaco_js_url` | `str` | jsDelivr CDN | Monaco Editor loader script |
| `oauth2_redirect_url` | `str \| None` | `None` | OAuth2 redirect URL |
| `init_oauth` | `dict \| None` | `None` | Passed to `SwaggerUI.initOAuth()` |
| `swagger_ui_parameters` | `dict \| None` | `None` | Extra `SwaggerUIBundle` options |

---

## 🛠️ How it works

coolswagger registers a custom `MonacoPlugin` inside `SwaggerUIBundle`. The plugin wraps Swagger UI's internal `TextArea` component — every request-body textarea is replaced with a Monaco editor instance (JSON mode, auto-layout, theme-aware). Editor instances are indexed by `"METHOD /path"` so the patched `ui.execute` can pull the correct content and override `req.requestBody` right before the HTTP call is made.

Dark mode is a CSS class on `<body>` toggled by a fixed button, with the choice persisted in `localStorage` under `swagger-theme`.

---

## 🤝 Contributing

Issues and PRs are welcome at [github.com/SasquatchMe/coolswagger](https://github.com/SasquatchMe/coolswagger).

---

## 📋 Changelog

### 0.1.2
- Resizable Monaco editor — drag handle below the editor to adjust height
- Fixed dark mode syntax highlighting — Monaco token colors no longer overridden by Swagger UI CSS
- VS Code-aligned dark palette (`#1e1e1e` background, `#d4d4d4` text) — matches Monaco's native theme
- Monaco editor now stretches to full container width

### 0.1.1
- Removed signature from page footer
- Added `skip-existing` to publish workflow to prevent duplicate upload errors

### 0.1.0
- Initial release — dark/light theme toggle, Monaco Editor for request bodies, drop-in FastAPI router
