Metadata-Version: 2.1
Name: apispec-ui
Version: 0.1.4
Summary: Generate UI interactive API's from APISpec specifications.
Home-page: https://github.com/codectl/apispec-ui
License: MIT
Keywords: flaskful,swagger,openapi,oas,oas2,oas3,rest,api,web,flask,python,python3
Author: Renato Damas
Author-email: rena2damas@gmail.com
Requires-Python: >=3.7,<4.0
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Requires-Dist: Flask (>=2.2.2,<3.0.0)
Requires-Dist: apispec[yaml] (>=6.0.2,<7.0.0)
Requires-Dist: environs (>=9.5.0,<10.0.0)
Requires-Dist: gunicorn (>=20.1.0,<21.0.0)
Project-URL: Repository, https://github.com/codectl/apispec-ui
Project-URL: issues, https://github.com/codectl/apispec-ui/issues
Description-Content-Type: text/x-rst

**********
apispec-ui
**********

.. image:: https://img.shields.io/pypi/v/apispec-ui
    :target: https://pypi.org/project/apispec-ui
    :alt: PyPI version
.. image:: https://github.com/codectl/apispec-ui/actions/workflows/ci.yaml/badge.svg
    :target: https://github.com/codectl/apispec-ui/actions/workflows/ci.yaml
    :alt: CI
.. image:: https://codecov.io/gh/codectl/apispec-ui/branch/master/graph/badge.svg
    :target: https://app.codecov.io/gh/codectl/apispec-ui/branch/master
    :alt: codecov
.. image:: https://img.shields.io/badge/code%20style-black-000000.svg
    :target: https://github.com/psf/black
    :alt: code style: black
.. image:: https://img.shields.io/badge/License-MIT-yellow.svg
    :target: https://opensource.org/licenses/MIT
    :alt: license: MIT

A library to generate a UI interface from an `APISpec <https://github
.com/marshmallow-code/apispec>`__ specification. As per the APISpec initiative, it
currently supports `OpenAPI Specification <https://github
.com/OAI/OpenAPI-Specification>`__ (aka. Swagger specification) and `SwaggerUI
<https://swagger.io/tools/swagger-ui/>`__.

Features
========
* Supports the OpenAPI Specification (versions 2 and 3)
* Supports SwaggerUI for Swagger specifications (latest version - 4.0.0)
* Currently supported frameworks include:

  * Flask


Installation
============
Install the package directly from ``PyPI`` (recommended):

.. code-block:: bash

    $ pip install -U apispec-ui


Plugin dependencies like ``apispec`` and ``Flask`` are not installed with the package
by default. To have it installed, do like so:

.. code-block:: bash

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

Example usage
=============
A simple example on how to work with a ``Flask`` application:

.. code-block:: python

    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="Test API",
        version="0.1.0",
        openapi_version="3.0.3",
        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:

.. code-block:: python

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

.. code-block:: bash

    # ensure tox is installed
    $ tox

Run linter only:

.. code-block:: bash

    $ tox -e lint

Optionally, run coverage as well with:

.. code-block:: bash

    $ tox -e coverage

License
=======
MIT licensed. See `LICENSE <LICENSE>`__.

