apispec-ui

A library to generate a UI interface from an APISpec specification. As per the APISpec initiative, it currently supports OpenAPI Specification (aka. Swagger specification) and SwaggerUI.

Features

• Support for the OpenAPI Specification (versions 2 and 3)
• Compatibility with SwaggerUI (latest version - 4.18.1)
• Support for frameworks which include:
  • Flask

Installation

Install the package directly from PyPI (recommended):

$ pip install -U apispec-ui

Plugin dependencies like apispec and Flask are not installed with the package by default. To have apispec and Flask installed, run:

$ pip install -U apispec-ui[apispec,flask]

Example usage

A simple example on how to work with a Flask application:

from apispec import APISpec
from apispec.ext.marshmallow import MarshmallowPlugin
from apispec_plugins import FlaskPlugin
from apispec_ui.flask import Swagger
from flask import Flask

app = Flask(__name__)
apispec = APISpec(
    title="Pet Store",
    version="1.0.0",
    openapi_version="3.1.0",
    plugins=(FlaskPlugin(), MarshmallowPlugin()),  # optional
)
...
Swagger(app=app, apispec=apispec, config={})

With this example, the application contains 2 extra views:

• swagger.ui: endpoint to serve SwaggerUI
• swagger.specs: endpoint to serve swagger specs, in yaml

With configs parameter one can tweak some parameters:

config = {
    "swaggerui": True,  # enable/disable SwaggerUI
    "swagger_route": "/api/",  # change swagger routes
    "swagger_static": "/static/",  # change location for static files
    "swagger_favicon": "favicon.ico",  # change favicon
    "swagger_hide_bar": True,  # hide SwaggerUI top bar
}

These settings can also be configured through the SWAGGER config variable that is part of the app config.

In terms of precedence, the config that takes the most precedence is the config parameter from Swagger class, followed by the SWAGGER app config.

Tests & linting 🚥

Run tests with tox:

# ensure tox is installed
$ tox

Run linter only:

$ tox -e lint

Optionally, run coverage as well with:

$ tox -e coverage

License

MIT licensed. See LICENSE.