Plugins for apispec
Project description
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.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for apispec_plugins-0.1.3-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | cc46ca090ca88dd9e734b328d2a115e3e238aec53b658d06545d0bf71f1d3dbd |
|
MD5 | 59d9bfe3fc48224d691115d58b2b90d4 |
|
BLAKE2b-256 | 7b75192177878bc4794594f34fc0108b02defb47e8aca3b8ca665cdc0ceb0113 |