Swagger UI for Python

25.7.1 verified Mon Apr 27 auth: no python

A library to easily integrate Swagger UI and Swagger Editor into Python web frameworks (Tornado, Flask, Quart, Sanic, Falcon). Current version 25.7.1. Releases follow CalVer, approximately monthly.

pip install swagger-ui-py

Common errors

error ModuleNotFoundError: No module named 'swagger_ui' ↓

cause Package installed as `swagger-ui-py` but imported as `swagger_ui`. If you see this error, the package might not be installed, or you used the wrong import name (e.g., `import swagger-ui`).

fix

Install: pip install swagger-ui-py. Import: from swagger_ui import ....

error TypeError: api_doc() got an unexpected keyword argument 'spec_url' ↓

cause In v25.x, `api_doc` changed from accepting keyword arguments to accepting a `config` dictionary.

fix

Use api_doc(app, config={'spec_url': '/spec'}).

error AttributeError: 'Response' object has no attribute 'body' ↓

cause Using Falcon >=3.0 with swagger-ui-py <25.7.1, where the library still used the deprecated `resp.body` attribute.

fix

Upgrade to swagger-ui-py >=25.7.1.

error swagger-ui is not a package (no import 'swagger-ui') ↓

cause The hyphen in the package name causes confusion; the importable module uses underscore.

fix

Always import as from swagger_ui import ....

Warnings

breaking The `api_doc` function signature changed in v25.x. Previously it accepted `config_spec` and other keyword arguments; now it expects a `config` dictionary. ↓

fix Use `api_doc(app, config={'spec_url': '/spec'})` instead of old `api_doc(app, spec_url='/spec')`.

deprecated The old `swagger-ui` import path (without underscore) is deprecated. Use `swagger_ui` (with underscore) as the package name. ↓

fix Change `import swagger_ui` to correct spelling: `from swagger_ui import ...`.

gotcha If using Falcon, the `resp.body` attribute was deprecated in Falcon 3.0+. In v25.7.1, the library correctly uses `resp.text`, but older versions (<25.7.1) may trigger a DeprecationWarning or error with Falcon >=3.0. ↓

fix Update to swagger-ui-py >=25.7.1 or pin Falcon <3.0.

gotcha The `custom_css` parameter introduced in v25.7.1 expects a string path or URL to a CSS file, not the CSS content itself. Passing CSS content directly will cause a 404 or broken styling. ↓

fix Use `custom_css='/path/to/custom.css'` or a URL, not inline CSS.

deprecated The `host_injection` parameter is deprecated as of v23.9.23; use `config` dictionary to disable host injection. ↓

fix Set `config={'disable_host_injection': True}` in `api_doc`.

Imports

get_swagger_ui_html

from swagger_ui import get_swagger_ui_html

get_swagger_editor_html

from swagger_ui import get_swagger_editor_html

swagger_ui_path
```
from swagger_ui import swagger_ui_path
```

swagger_editor_path

from swagger_ui import swagger_editor_path

Quickstart

Integrate Swagger UI in a Flask app using the api_doc function.

from flask import Flask, jsonify, send_from_directory
from swagger_ui import api_doc

app = Flask(__name__)

@app.route('/spec')
def spec():
    return jsonify({
        "openapi": "3.0.0",
        "info": {"title": "Sample API", "version": "1.0.0"},
        "paths": {}
    })

# Serve swagger UI at /docs, with spec at /spec
api_doc(app, config={'spec_url': '/spec'})

if __name__ == '__main__':
    app.run()