Dark mode Swagger for your FastAPI apps
Project description
This module enables Swagger OpenAPI docs that default to dark mode but can be toggled on or off, specifically for FastAPI. Requires virtually zero work to implement. DarkSwag
has an optional argument for adding your project or company logo. Implementation is cake, depending on how you implement it. The easiest implementation method involves importing the FastAPI
class override, and that's it.
Installation
python -m pip install dark_swag
Implementation
There are three main ways you can implement this into your API.
Method 1: FastAPI class override (easiest)
The easiest is to import the FastAPI
override, as it requires no additional change to your existing code.
from dark_swag import FastAPI
Full example of this implementation
Method 2: Docs route factory (easy)
You can import the get_dark_router
factory function to generate a route that you can immediately add to your existing FastAPI
instance.
from dark_swag import get_dark_router
app = FastAPI(docs_url=None) # this argument is required if you use this implementation
docs_router = get_dark_router(app)
app.include_router(docs_router)
Method 3: Manually define the docs routes (if you need it)
You can manually define the docs route(s) yourself, and use the helper function to generate the dark-enabled html. This is a lot more tedius and involved, so you probably won't do it this way unless you have some very specific use case, but if you need it, this is how you can do it. The link below the example code has a full implementation that matches the first two easier methods.
(The example in this code block doesn't support toggling back to light mode, but the full example in the file does)
from fastapi import FastAPI
from dark_swag import get_dark_swagger_html
app = FastAPI(docs_url=None) # this argument is required if you use this implementation
@app.get('/docs', include_in_schema=False)
async def dark_swagger():
return get_dark_swagger_html(app)
Note!
Be sure to add docs_url=None
to your FastAPI
instantiation if you use methods #2
or #3
, else it won't work, since FastAPI
will generate the /docs
endpoint internally and your manual definition of it won't overwrite it.
This is still 100% Swagger
. We just inject CSS to create the dark theme in-flight before it's sent to the caller. Reasoning for this is at the very bottom fo this doc.
Features
Custom Logo
You can add your own logo to the top-right corner of the Swagger
doc by passing a URL or path to an image to the argument logo
.
You'll probably need to make a route to host them from, or you can also pass in the image as base64 format like this:
- If you used the
FastAPI
override, you add the argument to it:
# mounted path, like a FastAPI static endpoint
app = FastAPI(logo='static/logo.png')
""" OR """
# raw base64 string with the appropriate prefix (below example is for an SVG)
app = FastAPI(logo="data:image/svg+xml;base64,xucz0i... (shortened for illustration) ...L3d3dy")
- If you used the
dark_router
, you add the argument to the factory function:
dark_router = get_dark_router(app, logo='static/logo.png')
- If you used the helper function to get the
Swagger
HTML and manually defined your/docs
endpoint, you add the argument to that helper function:
return get_dark_swagger_html(app, logo='static/logo.png')
The logo placement looks like this:
Background Text
Like the above logo, this is also purely for aesthetics. You basically can pass in a word or short phrase, and it gets drawn on the background in a watermark-like fashion, purely to help branding or for aesthetics. Longer text will probably get truncated due to how this effect was accomplished.
- If you used the
FastAPI
override, you addbackground_text
argument with it:
app = FastAPI(background_text='Example 3')
- If you used the
dark_router
, you add thebackground_text
argument to it:
dark_router = get_dark_router(app, background_text='Example 3')
- If you used the helper function
get_dark_swagger_html
, you do the same thing:
return get_dark_swagger_html(app, background_text='Example 3')
The text looks like this:
Aziz, light!
For our friends and colleagues that enjoy being flashbanged when they open documentation, this built-in feature is for toggling light mode. There's a toggle button at the top right. Implementation methods #1
and #2
support this without doing anything extra.
If you set DarkSwag
up using the completely manual method #3
, you need to define both /docs
and /docs_light
routes, as this just links between the two. See example3.py for a working example of this.
If you click the Light Mode
toggle at the top right, it will enable light mode, and it will look very similar to the standard Swagger
docs, only it still supports the addition of your own logo and the watermark-like background text. There's also a toggle for switching back to dark mode. The toggle isn't toggling CSS. It's just linking back and forth between /docs
and /docs_light
.
Here's what light mode looks like:
Notes
Technically, there is a "cleaner" way to do this. FastAPI
provides a function you can call that generates the swagger doc, and you can pass in the javascript and css files, so there's an opportunity to feed it your own.
The reason why I did NOT go this route, is simply due to practicality. Once de-minified, the Swagger
style sheet is 11,490
lines long when pretty-printed. It's obviously built from a packager and coalesced into a single file, with media queries to cover all bases, so it's no surprise why it can be so massive, but I wasn't about to invest that much time on this, so I went the route that most do: inject override CSS into the head before you return the HTMLResponse
. It's pretty limiting only being able to touch CSS, but I was still able to figure some things out like toggling light/dark modes, and allowing for an optional custom logo.
If anyone has a better plan, feel free to contribute. It's hard to test all possible cases as OpenAPI supports a ton of stuff, so there's a good chance some things might not be fully adjusted for dark mode, but they're easy to add as they're found.
Bananas, isn't it?
Project details
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for dark_swag-1.0.0-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | d6c3d1e61425c9e09d2802e3ab3df7a95e43d89e224d8d5b79c99eee87510253 |
|
MD5 | 974181ba9ec0d753a85c4088bbadfaf4 |
|
BLAKE2b-256 | 031351dba53aa4ae3d4e5e40f02353178c798dbba6dd79fc196348a3796cb878 |