apispec-plugins 0.1.3

Plugins for apispec

APISpec plugins for easy integration with different components (web frameworks, packages, etc).

Features

• Supports the OpenAPI Specification (versions 2 and 3)

• Currently supported frameworks/plugins include:

  • apispec_plugins.webframeworks.flask

Installation

Install the package directly from PyPI (recommended):

$ pip install apispec-plugins

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

$ pip install apispec-plugins[flask]

Example Usage

from apispec import APISpec
from apispec_plugins.webframeworks.flask import FlaskPlugin
from flask import Flask

spec = APISpec(
    title="Pet Store",
    version="1.0.0",
    openapi_version="2.0",
    info=dict(description="A minimal pet store API"),
    plugins=(FlaskPlugin(),),
)

app = Flask(__name__)


@app.route("/pet/<petId>")
def pet(petId):
    """Find pet by ID.
    ---
    get:
        parameters:
            - in: path
              name: petId
        responses:
            200:
                description: display pet data
    """
    return f"Display pet with ID {petId}"


# 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=pet)

Alternatively, a Flask MethodView can be used:

from flask.views import MethodView


class PetAPI(MethodView):
    def get(self, petId):
        # get pet by ID
        pass


app.add_url_rule("/pet/<petId>", view_func=PetAPI.as_view("pet_view"))

There is also easy integration with other packages like Flask-RESTful:

from flask_restful import Api, Resource


class PetAPI(Resource):
    def get(self, petId):
        # get pet by ID
        pass


api = Api(app)
api.add_resource(PetAPI, "/pet/<petId>", endpoint="pet")

Dynamic specs

As seen so far, specs are specified in the docstring of the view or class. However, with the spec_from decorator, one can dynamically set specs:

from apispec_plugins import spec_from


@spec_from(
    {
        "parameters": {"in": "path", "name": "petId"},
        "responses": {200: {"description": "display pet data"}},
    }
)
def pet(petID):
    """Find pet by ID."""
    pass

Why not apispec-webframeworks?

The conceiving of this project was based on apispec-webframeworks. While that project is focused on integrating web frameworks with APISpec, this repository goes a step further in providing the best integration possible with the APISpec standards. Some limitations on that project were also addressed, like:

• a path cannot register no more than 1 single rule per endpoint;

• support for additional libraries like Flask-RESTful;

• limited docstring spec processing;

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.