coolswagger

Beautiful Swagger UI for FastAPI — dark/light theme + Monaco Editor

These details have been verified by PyPI

Project links

GitHub Statistics

Maintainers

These details have not been verified by PyPI

Project description

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

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

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.

✨ 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

# 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:

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

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

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

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)

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.

📋 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

Project details

These details have been verified by PyPI

Project links

GitHub Statistics

Maintainers

SasquatchMe

These details have not been verified by PyPI

Release history Release notifications | RSS feed

This version

0.1.2

Apr 30, 2026

0.1.1

Apr 30, 2026

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

coolswagger-0.1.2.tar.gz (10.0 kB view details)

Uploaded Apr 30, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

coolswagger-0.1.2-py3-none-any.whl (9.4 kB view details)

Uploaded Apr 30, 2026 Python 3

File details

Details for the file coolswagger-0.1.2.tar.gz.

File metadata

Download URL: coolswagger-0.1.2.tar.gz
Upload date: Apr 30, 2026
Size: 10.0 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for coolswagger-0.1.2.tar.gz
Algorithm	Hash digest
SHA256	`f5a3f6a655e1d6d4ac78c2bc1d0925bf511509afd4c1ebbfff5d663d4f28d240`
MD5	`6ddce2b68913069f0bb8d32ade21b2e2`
BLAKE2b-256	`42c4b5026eea74f757c4a7d146373c1a9e34172474a06b314223e94794300ca1`

See more details on using hashes here.

Provenance

The following attestation bundles were made for coolswagger-0.1.2.tar.gz:

Publisher: publish.yml on SasquatchMe/coolswagger

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: coolswagger-0.1.2.tar.gz
- Subject digest: f5a3f6a655e1d6d4ac78c2bc1d0925bf511509afd4c1ebbfff5d663d4f28d240
- Sigstore transparency entry: 1413479316
- Sigstore integration time: Apr 30, 2026
Source repository:
- Permalink: SasquatchMe/coolswagger@4c2050fd908d86dbe6ccfd76cb019a19f57e0eb7
- Branch / Tag: refs/tags/v0.1.2
- Owner: https://github.com/SasquatchMe
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: publish.yml@4c2050fd908d86dbe6ccfd76cb019a19f57e0eb7
- Trigger Event: push

File details

Details for the file coolswagger-0.1.2-py3-none-any.whl.

File metadata

Download URL: coolswagger-0.1.2-py3-none-any.whl
Upload date: Apr 30, 2026
Size: 9.4 kB
Tags: Python 3
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for coolswagger-0.1.2-py3-none-any.whl
Algorithm	Hash digest
SHA256	`f06ab31e3fc53df90b817d974c2c17c456f03e69de4053e3c149611905c0e57b`
MD5	`7b0a42a05a83a60df7559c2f3bf1a4e8`
BLAKE2b-256	`904ad45a1f0a66247c1b0eec262804a22f1249b7e6ba0f80a76fcc41224ac04c`

See more details on using hashes here.

Provenance

The following attestation bundles were made for coolswagger-0.1.2-py3-none-any.whl:

Publisher: publish.yml on SasquatchMe/coolswagger

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: coolswagger-0.1.2-py3-none-any.whl
- Subject digest: f06ab31e3fc53df90b817d974c2c17c456f03e69de4053e3c149611905c0e57b
- Sigstore transparency entry: 1413479417
- Sigstore integration time: Apr 30, 2026
Source repository:
- Permalink: SasquatchMe/coolswagger@4c2050fd908d86dbe6ccfd76cb019a19f57e0eb7
- Branch / Tag: refs/tags/v0.1.2
- Owner: https://github.com/SasquatchMe
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: publish.yml@4c2050fd908d86dbe6ccfd76cb019a19f57e0eb7
- Trigger Event: push

coolswagger 0.1.2

Navigation

Verified details

Project links

GitHub Statistics

Maintainers

Unverified details

Meta

Classifiers

Project description

✨ What you get

📦 Installation

🚀 Quick start

⚙️ Advanced usage

SwaggerConfig helper

OAuth2

Custom Swagger UI parameters

Self-hosted / offline (no CDN)

📋 Parameters

🛠️ How it works

🤝 Contributing

📋 Changelog

0.1.2

0.1.1

0.1.0

Project details

Verified details

Project links

GitHub Statistics

Maintainers

Unverified details

Meta

Classifiers

Release history Release notifications | RSS feed

Download files

Source Distribution

Built Distribution

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance