Skip to main content

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

Project description

tests Version PyPi Version PyPi Downloads

Project Page

swagger-ui-py

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

Only support Python3.

Supported

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
    
  • 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.7.2. see https://github.com/swagger-api/swagger-ui.

Swagger Editor

Swagger Editor version is v4.11.1. see https://github.com/swagger-api/swagger-editor.

Update

You can update swagger ui and swagger editor version with

python3 tools/update.py --ui --editor

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

swagger-ui-py-23.9.23.tar.gz (8.4 MB view details)

Uploaded Source

Built Distribution

swagger_ui_py-23.9.23-py3-none-any.whl (8.5 MB view details)

Uploaded Python 3

File details

Details for the file swagger-ui-py-23.9.23.tar.gz.

File metadata

  • Download URL: swagger-ui-py-23.9.23.tar.gz
  • Upload date:
  • Size: 8.4 MB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/4.0.2 CPython/3.10.12

File hashes

Hashes for swagger-ui-py-23.9.23.tar.gz
Algorithm Hash digest
SHA256 454ed3a4413a109d3455da7260596a4d4421f3f2cf0298d3a6643c5047e6ea41
MD5 49fbca94fe9cc4a4ee71d8a3e9860b84
BLAKE2b-256 e554f0495cd1d33aa12a8b4cd69194558604599a3e9e28cdfaf62e6ffa595407

See more details on using hashes here.

File details

Details for the file swagger_ui_py-23.9.23-py3-none-any.whl.

File metadata

File hashes

Hashes for swagger_ui_py-23.9.23-py3-none-any.whl
Algorithm Hash digest
SHA256 e86fb81a1d67f6a775a11852943c805f109385e9340b9c3a4a087e71c9773d77
MD5 56a68f1d42c734aa2df1fa161542f246
BLAKE2b-256 c0e6be065ce1553646836a706a788bb6251b01e2dd2c7a080ff2dbdcfa7df6ca

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page