swagger-ui-py


Nameswagger-ui-py JSON
Version 23.9.23 PyPI version JSON
download
home_pagehttps://github.com/PWZER/swagger-ui-py
SummarySwagger UI for Python web framework, such as Tornado, Flask, Quart, Sanic and Falcon.
upload_time2023-09-23 16:37:57
maintainer
docs_urlNone
authorPWZER
requires_python>=3.0.0
licenseApache License 2.0
keywords
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls. 
            [![tests](https://github.com/PWZER/swagger-ui-py/actions/workflows/lint-and-pytest.yml/badge.svg)](https://github.com/PWZER/swagger-ui-py/actions/workflows/lint-and-pytest.yml)
[![Version](https://badge.fury.io/gh/PWZER%2Fswagger-ui-py.svg)](https://github.com/PWZER/swagger-ui-py/tags)
[![PyPi Version](https://img.shields.io/pypi/v/swagger-ui-py.svg)](https://pypi.org/project/swagger-ui-py/)
[![PyPi Downloads](https://pepy.tech/badge/swagger-ui-py)](https://pepy.tech/project/swagger-ui-py)

[Project Page](https://pwzer.github.io/swagger-ui-py/)

# swagger-ui-py
Swagger UI for Python web framework, such Tornado, Flask, Quart, aiohttp, Sanic and Falcon.

Only support Python3.

## Supported

- [Tornado](https://www.tornadoweb.org/en/stable/)
- [Flask](https://flask.palletsprojects.com/)
- [Sanic](https://sanicframework.org/en/)
- [AIOHTTP](https://docs.aiohttp.org/en/stable/)
- [Quart](https://pgjones.gitlab.io/quart/)
- [Starlette](https://www.starlette.io/)
- [Falcon](https://falcon.readthedocs.io/en/stable/)
- [Bottle](https://bottlepy.org/docs/dev/)
- [Chalice](https://aws.github.io/chalice/index.html)

You can print supported list use command

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

> If you want to add supported frameworks, you can refer to [Flask Support](/swagger_ui/handlers/flask.py) or [Falcon Support](/swagger_ui/handlers/falcon.py), Implement the corresponding `handler` and `match` function.

## Usage

- Install

  ```bash
  pip3 install swagger-ui-py
  ```

- Code

  Using the local config file

  ```python
  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](https://en.wikipedia.org/wiki/Cross-origin_resource_sharing)

  ```python
  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

  ```python
  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

  ```python
  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

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

  And keep the old way

  ```python
  # 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/](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\""`.

  ```python
  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](https://swagger.io/docs/open-source-tools/swagger-ui/usage/configuration/).

## OAuth2 Configuration

  The format is similar to `parameters`.

  ```python
  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](https://swagger.io/docs/open-source-tools/swagger-ui/usage/oauth2/).

## Swagger UI
Swagger UI version is `v5.7.2`. see [https://github.com/swagger-api/swagger-ui](https://github.com/swagger-api/swagger-ui).

## Swagger Editor
Swagger Editor version is `v4.11.1`. see [https://github.com/swagger-api/swagger-editor](https://github.com/swagger-api/swagger-editor).

## Update
You can update swagger ui and swagger editor version with

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

Raw data

            {
    "_id": null,
    "home_page": "https://github.com/PWZER/swagger-ui-py",
    "name": "swagger-ui-py",
    "maintainer": "",
    "docs_url": null,
    "requires_python": ">=3.0.0",
    "maintainer_email": "",
    "keywords": "",
    "author": "PWZER",
    "author_email": "pwzergo@gmail.com",
    "download_url": "https://files.pythonhosted.org/packages/e5/54/f0495cd1d33aa12a8b4cd69194558604599a3e9e28cdfaf62e6ffa595407/swagger-ui-py-23.9.23.tar.gz",
    "platform": null,
    "description": "[![tests](https://github.com/PWZER/swagger-ui-py/actions/workflows/lint-and-pytest.yml/badge.svg)](https://github.com/PWZER/swagger-ui-py/actions/workflows/lint-and-pytest.yml)\n[![Version](https://badge.fury.io/gh/PWZER%2Fswagger-ui-py.svg)](https://github.com/PWZER/swagger-ui-py/tags)\n[![PyPi Version](https://img.shields.io/pypi/v/swagger-ui-py.svg)](https://pypi.org/project/swagger-ui-py/)\n[![PyPi Downloads](https://pepy.tech/badge/swagger-ui-py)](https://pepy.tech/project/swagger-ui-py)\n\n[Project Page](https://pwzer.github.io/swagger-ui-py/)\n\n# swagger-ui-py\nSwagger UI for Python web framework, such Tornado, Flask, Quart, aiohttp, Sanic and Falcon.\n\nOnly support Python3.\n\n## Supported\n\n- [Tornado](https://www.tornadoweb.org/en/stable/)\n- [Flask](https://flask.palletsprojects.com/)\n- [Sanic](https://sanicframework.org/en/)\n- [AIOHTTP](https://docs.aiohttp.org/en/stable/)\n- [Quart](https://pgjones.gitlab.io/quart/)\n- [Starlette](https://www.starlette.io/)\n- [Falcon](https://falcon.readthedocs.io/en/stable/)\n- [Bottle](https://bottlepy.org/docs/dev/)\n- [Chalice](https://aws.github.io/chalice/index.html)\n\nYou can print supported list use command\n\n```bash\npython3 -c \"from swagger_ui import supported_list; print(supported_list)\"\n```\n\n> If you want to add supported frameworks, you can refer to [Flask Support](/swagger_ui/handlers/flask.py) or [Falcon Support](/swagger_ui/handlers/falcon.py), Implement the corresponding `handler` and `match` function.\n\n## Usage\n\n- Install\n\n  ```bash\n  pip3 install swagger-ui-py\n  ```\n\n- Code\n\n  Using the local config file\n\n  ```python\n  from swagger_ui import api_doc\n  api_doc(app, config_path='./config/test.yaml', url_prefix='/api/doc', title='API doc')\n  ```\n\n  Or using config url, but need to suport [CORS](https://en.wikipedia.org/wiki/Cross-origin_resource_sharing)\n\n  ```python\n  api_doc(app, config_url='https://petstore.swagger.io/v2/swagger.json', url_prefix='/api/doc', title='API doc')\n  ```\n\n  Or using the config spec string\n\n  ```python\n  from swagger_ui import api_doc\n  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\":{}}'\n\n  api_doc(app, config_spec=spec_string, url_prefix='/api/doc', title='API doc')\n  ```\n\n  Or using the config dict\n\n  ```python\n  from swagger_ui import api_doc\n  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\":{}}\n\n  api_doc(app, config=config, url_prefix='/api/doc', title='API doc')\n  ```\n\n  And suport config file with editor\n\n  ```python\n  api_doc(app, config_path='./config/test.yaml', editor=True)\n  ```\n\n  And keep the old way\n\n  ```python\n  # for Tornado\n  from swagger_ui import tornado_api_doc\n  tornado_api_doc(app, config_path='./conf/test.yaml', url_prefix='/api/doc', title='API doc')\n\n  # for Sanic\n  from swagger_ui import sanic_api_doc\n  sanic_api_doc(app, config_path='./conf/test.yaml', url_prefix='/api/doc', title='API doc')\n\n  # for Flask\n  from swagger_ui import flask_api_doc\n  flask_api_doc(app, config_path='./conf/test.yaml', url_prefix='/api/doc', title='API doc')\n\n  # for Quart\n  from swagger_ui import quart_api_doc\n  quart_api_doc(app, config_path='./conf/test.yaml', url_prefix='/api/doc', title='API doc')\n\n  # for aiohttp\n  from swagger_ui import aiohttp_api_doc\n  aiohttp_api_doc(app, config_path='./conf/test.yaml', url_prefix='/api/doc', title='API doc')\n\n  # for Falcon\n  from swagger_ui import falcon_api_doc\n  falcon_api_doc(app, config_path='./conf/test.yaml', url_prefix='/api/doc', title='API doc')\n  ```\n  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.\n\n- Edit `Swagger` config file (JSON or YAML)\n\n  Please see [https://swagger.io/resources/open-api/](https://swagger.io/resources/open-api/).\n\n- Access\n\n  Open `http://<host>:<port>/api/doc/editor`, you can edit api doc config file.\n\n  Open `http://<host>:<port>/api/doc` view api doc.\n\n## SwaggerUI Configuration\n\n  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.\n  Such as `\"layout\": \"\\\"StandaloneLayout\\\"\"`.\n\n  ```python\n  parameters = {\n      \"deepLinking\": \"true\",\n      \"displayRequestDuration\": \"true\",\n      \"layout\": \"\\\"StandaloneLayout\\\"\",\n      \"plugins\": \"[SwaggerUIBundle.plugins.DownloadUrl]\",\n      \"presets\": \"[SwaggerUIBundle.presets.apis, SwaggerUIStandalonePreset]\",\n  }\n  api_doc(app, config_path='./config/test.yaml', parameters=parameters)\n  ```\n\n  For details about parameters configuration, see the official documentation [Parameters Configuration](https://swagger.io/docs/open-source-tools/swagger-ui/usage/configuration/).\n\n## OAuth2 Configuration\n\n  The format is similar to `parameters`.\n\n  ```python\n  oauth2_config = {\n      \"clientId\": \"\\\"your-client-id\\\"\",\n      \"clientSecret\": \"\\\"your-client-secret-if-required\\\"\",\n      \"realm\": \"\\\"your-realms\\\"\",\n      \"appName\": \"\\\"your-app-name\\\"\",\n      \"scopeSeparator\": \"\\\" \\\"\",\n      \"scopes\": \"\\\"openid profile\\\"\",\n      \"additionalQueryStringParams\": \"{test: \\\"hello\\\"}\",\n      \"usePkceWithAuthorizationCodeGrant\": True,\n  }\n  api_doc(app, config_path='./config/test.yaml', oauth2_config=oauth2_config)\n  ```\n\n  For details about OAuth2 configuration, see the official documentation [OAuth2 Configuration](https://swagger.io/docs/open-source-tools/swagger-ui/usage/oauth2/).\n\n## Swagger UI\nSwagger UI version is `v5.7.2`. see [https://github.com/swagger-api/swagger-ui](https://github.com/swagger-api/swagger-ui).\n\n## Swagger Editor\nSwagger Editor version is `v4.11.1`. see [https://github.com/swagger-api/swagger-editor](https://github.com/swagger-api/swagger-editor).\n\n## Update\nYou can update swagger ui and swagger editor version with\n\n```bash\npython3 tools/update.py --ui --editor\n```\n\n\n",
    "bugtrack_url": null,
    "license": "Apache License 2.0",
    "summary": "Swagger UI for Python web framework, such as Tornado, Flask, Quart, Sanic and Falcon.",
    "version": "23.9.23",
    "project_urls": {
        "Homepage": "https://github.com/PWZER/swagger-ui-py"
    },
    "split_keywords": [],
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "c0e6be065ce1553646836a706a788bb6251b01e2dd2c7a080ff2dbdcfa7df6ca",
                "md5": "56a68f1d42c734aa2df1fa161542f246",
                "sha256": "e86fb81a1d67f6a775a11852943c805f109385e9340b9c3a4a087e71c9773d77"
            },
            "downloads": -1,
            "filename": "swagger_ui_py-23.9.23-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "56a68f1d42c734aa2df1fa161542f246",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.0.0",
            "size": 8455558,
            "upload_time": "2023-09-23T16:37:44",
            "upload_time_iso_8601": "2023-09-23T16:37:44.499019Z",
            "url": "https://files.pythonhosted.org/packages/c0/e6/be065ce1553646836a706a788bb6251b01e2dd2c7a080ff2dbdcfa7df6ca/swagger_ui_py-23.9.23-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "e554f0495cd1d33aa12a8b4cd69194558604599a3e9e28cdfaf62e6ffa595407",
                "md5": "49fbca94fe9cc4a4ee71d8a3e9860b84",
                "sha256": "454ed3a4413a109d3455da7260596a4d4421f3f2cf0298d3a6643c5047e6ea41"
            },
            "downloads": -1,
            "filename": "swagger-ui-py-23.9.23.tar.gz",
            "has_sig": false,
            "md5_digest": "49fbca94fe9cc4a4ee71d8a3e9860b84",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.0.0",
            "size": 8367222,
            "upload_time": "2023-09-23T16:37:57",
            "upload_time_iso_8601": "2023-09-23T16:37:57.350908Z",
            "url": "https://files.pythonhosted.org/packages/e5/54/f0495cd1d33aa12a8b4cd69194558604599a3e9e28cdfaf62e6ffa595407/swagger-ui-py-23.9.23.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2023-09-23 16:37:57",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "PWZER",
    "github_project": "swagger-ui-py",
    "travis_ci": false,
    "coveralls": false,
    "github_actions": true,
    "tox": true,
    "lcname": "swagger-ui-py"
}
PWZER
Elapsed time: 0.12795s