Project Page

swagger-ui-py-x

Swagger UI for Python web framework, such Tornado, Flask, Quart, aiohttp, Sanic and Falcon.

Requires Python 3.12 or newer.

Supported

• Tornado
• Flask
• Sanic
• AIOHTTP
• Quart
• Starlette
• Falcon
• Bottle
• Chalice

You can print supported list use command

python3 -c "from swagger_ui import supported_list; print(supported_list)"

If you want to add supported frameworks, you can refer to Flask Support or Falcon Support, Implement the corresponding handler and match function.

Usage

• Install

  pip3 install swagger-ui-py-x
  

• Code

  Using the local config file

  from swagger_ui import api_doc
  api_doc(app, config_path='./config/test.yaml', url_prefix='/api/doc', title='API doc')
  

  Or using config url, but need to suport CORS

  api_doc(app, config_url='https://petstore.swagger.io/v2/swagger.json', url_prefix='/api/doc', title='API doc')
  

  Or using the config spec string

  from swagger_ui import api_doc
  spec_string = '{"openapi":"3.0.1","info":{"title":"python-swagger-ui test api","description":"python-swagger-ui test api","version":"1.0.0"},"servers":[{"url":"http://127.0.0.1:8989/api"}],"tags":[{"name":"default","description":"default tag"}],"paths":{"/hello/world":{"get":{"tags":["default"],"summary":"output hello world.","responses":{"200":{"description":"OK","content":{"application/text":{"schema":{"type":"object","example":"Hello World!!!"}}}}}}}},"components":{}}'
  
  api_doc(app, config_spec=spec_string, url_prefix='/api/doc', title='API doc')
  

  Or using the config dict

  from swagger_ui import api_doc
  config = {"openapi":"3.0.1","info":{"title":"python-swagger-ui test api","description":"python-swagger-ui test api","version":"1.0.0"},"servers":[{"url":"http://127.0.0.1:8989/api"}],"tags":[{"name":"default","description":"default tag"}],"paths":{"/hello/world":{"get":{"tags":["default"],"summary":"output hello world.","responses":{"200":{"description":"OK","content":{"application/text":{"schema":{"type":"object","example":"Hello World!!!"}}}}}}}},"components":{}}
  
  api_doc(app, config=config, url_prefix='/api/doc', title='API doc')
  

  And suport config file with editor

  api_doc(app, config_path='./config/test.yaml', editor=True)
  

  And keep the old way

  # for Tornado
  from swagger_ui import tornado_api_doc
  tornado_api_doc(app, config_path='./conf/test.yaml', url_prefix='/api/doc', title='API doc')
  
  # for Sanic
  from swagger_ui import sanic_api_doc
  sanic_api_doc(app, config_path='./conf/test.yaml', url_prefix='/api/doc', title='API doc')
  
  # for Flask
  from swagger_ui import flask_api_doc
  flask_api_doc(app, config_path='./conf/test.yaml', url_prefix='/api/doc', title='API doc')
  
  # for Quart
  from swagger_ui import quart_api_doc
  quart_api_doc(app, config_path='./conf/test.yaml', url_prefix='/api/doc', title='API doc')
  
  # for aiohttp
  from swagger_ui import aiohttp_api_doc
  aiohttp_api_doc(app, config_path='./conf/test.yaml', url_prefix='/api/doc', title='API doc')
  
  # for Falcon
  from swagger_ui import falcon_api_doc
  falcon_api_doc(app, config_path='./conf/test.yaml', url_prefix='/api/doc', title='API doc')
  

  Passing a value to the keyword argument host_inject will disable the behaviour which injects a host value into the specification served by Swagger UI.

• Edit Swagger config file (JSON or YAML)

  Please see https://swagger.io/resources/open-api/.

• Access

  Open http://<host>:<port>/api/doc/editor, you can edit api doc config file.

  Open http://<host>:<port>/api/doc view api doc.

SwaggerUI Configuration

You can configure Swagger parameters using the dictionary, Both key and value are of type str, if value is JavaScript string, you need to wrap the quotes around it. Such as "layout": "\"StandaloneLayout\"".

parameters = {
    "deepLinking": "true",
    "displayRequestDuration": "true",
    "layout": "\"StandaloneLayout\"",
    "plugins": "[SwaggerUIBundle.plugins.DownloadUrl]",
    "presets": "[SwaggerUIBundle.presets.apis, SwaggerUIStandalonePreset]",
}
api_doc(app, config_path='./config/test.yaml', parameters=parameters)

For details about parameters configuration, see the official documentation Parameters Configuration.

OAuth2 Configuration

The format is similar to parameters.

oauth2_config = {
    "clientId": "\"your-client-id\"",
    "clientSecret": "\"your-client-secret-if-required\"",
    "realm": "\"your-realms\"",
    "appName": "\"your-app-name\"",
    "scopeSeparator": "\" \"",
    "scopes": "\"openid profile\"",
    "additionalQueryStringParams": "{test: \"hello\"}",
    "usePkceWithAuthorizationCodeGrant": True,
}
api_doc(app, config_path='./config/test.yaml', oauth2_config=oauth2_config)

For details about OAuth2 configuration, see the official documentation OAuth2 Configuration.

Swagger UI

Swagger UI version is v5.33.0. see https://github.com/swagger-api/swagger-ui.

Swagger Editor

Swagger Editor version is v5.8.8. see https://github.com/swagger-api/swagger-editor.

Update

The shipped UI and Editor bundles are rebuilt with DOMPurify 3.4.16. Swagger UI 5.33.0 and Swagger Editor 5.8.8 are built from their current upstream releases. Editor uses its new React/Monaco interface with locally served workers and loads the configured specification. Python APIs, Flask blueprint configuration, the documentation template, and OAuth initialization are unchanged.

Use Python 3.12+, Node 22.22.0 and npm 10.9.4 to reproduce the assets:

uv run --python 3.12 python tools/update.py --ui --editor
uv run python tools/verify_assets.py

Versions, source archive checksums, and npm dependency locks are committed under tools/. The updater builds from source, preserves local templates, and rejects unexpected embedded DOMPurify sources. It never downloads floating latest bundles. See release and asset maintenance instructions for dependency updates, wheel verification, browser checks, and the approval-gated release procedure.

Contributing

If you are interested in becoming the developer or maintainer of this project, please contact me by email.