Metadata-Version: 2.1
Name: apispec-webframeworks
Version: 0.4.0
Summary: Web framework plugins for apispec.
Home-page: https://github.com/marshmallow-code/apispec-webframeworks
Author: Steven Loria
Author-email: sloria1@gmail.com
License: MIT
Project-URL: Funding, https://opencollective.com/marshmallow
Project-URL: Issues, https://github.com/marshmallow-code/apispec-webframeworks/issues
Keywords: apispec,swagger,openapi,specification,documentation,spec,rest,api,web,flask,tornado,bottle,frameworks
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Provides-Extra: dev
Provides-Extra: lint
Provides-Extra: tests

*********************
apispec-webframeworks
*********************

.. image:: https://badgen.net/pypi/v/apispec-webframeworks
    :target: https://pypi.org/project/apispec-webframeworks/
    :alt: PyPI version

.. image:: https://badgen.net/travis/marshmallow-code/apispec-webframeworks/master
    :target: https://travis-ci.org/marshmallow-code/apispec-webframeworks
    :alt: TravisCI build status

.. image:: https://badgen.net/badge/marshmallow/2,3?list=1
    :target: https://marshmallow.readthedocs.io/en/latest/upgrading.html
    :alt: marshmallow 2/3 compatible

`apispec <https://github.com/marshmallow-code/apispec>`_ plugins for
integrating with various web frameworks.

These plugins used to be in ``apispec.ext`` but have since
been moved to their own package.


Included plugins:

* ``apispec_webframeworks.bottle``
* ``apispec_webframeworks.flask``
* ``apispec_webframeworks.tornado``

Migration from ``apispec<1.0.0``
================================

To migrate from older versions of apispec, install this package
with

.. code-block:: console

    pip install apispec-webframeworks


Change your imports, like so:

.. code-block:: python

    # apispec<1.0.0
    from apispec.ext.flask import FlaskPlugin

    # apispec>=1.0.0
    from apispec_webframeworks.flask import FlaskPlugin

Example Usage
=============

.. code-block:: python

    from flask import Flask
    from apispec import APISpec
    from apispec.ext.marshmallow import MarshmallowPlugin
    from apispec_webframeworks.flask import FlaskPlugin
    from marshmallow import Schema, fields

    spec = APISpec(
       title='Gisty',
       version='1.0.0',
       info=dict(
           description='A minimal gist API'
       ),
       plugins=[
          FlaskPlugin(),
          MarshmallowPlugin(),
       ]
    )


    app = Flask(__name__)

    class GistParameter(Schema):
       gist_id = fields.Int()

    class GistSchema(Schema):
       id = fields.Int()
       content = fields.Str()

    @app.route('/gists/<gist_id>')
    def gist_detail(gist_id):
       """Gist detail view.
       ---
       get:
          parameters:
                - in: path
                schema: GistParameter
          responses:
                200:
                   schema: GistSchema
       """
       return 'details about gist {}'.format(gist_id)

    # Since `path` inspects the view and its route,
    # we need to be in a Flask request context
    with app.test_request_context():
       spec.path(view=gist_detail)

Documentation
=============

For documentation for a specific plugin, see its module docstring.


Development
===========

* Clone and cd into this repo
* Create and activate a virtual environment
* Install this package (in editable mode) and the development
  dependencies

::

    $ pip install '.[dev]'

* Install pre-commit hooks

::

    $ pre-commit install


Running tests
-------------

To run all tests: ::

    $ pytest

To run syntax checks: ::

    $ tox -e lint

(Optional) To run tests on Python 2.7, 3.5, 3.6, and 3.7 virtual environments (must have each interpreter installed): ::

    $ tox

License
=======

MIT licensed. See the bundled `LICENSE <https://github.com/marshmallow-code/apispec_webframeworks/blob/master/LICENSE>`_ file for more details.
