Plugins for apispec
Project description
APISpec plugins for easy integration with different components (web frameworks, packages, etc).
Features
Support for the OpenAPI Specification (versions 2 and 3)
Support for frameworks/plugins which include:
apispec_plugins.webframeworks.flask
apispec_plugins.ext.pydantic
Installation
Install the package directly from PyPI (recommended):
$ pip install apispec-plugins
Plugin dependencies like flask and pydantic are not installed with the package by default. To have flask and pydantic installed, run:
$ pip install apispec-plugins[flask,pydantic]
Example Usage
from typing import Optional
from apispec import APISpec
from apispec_plugins.base.mixin import RegistryMixin
from apispec_plugins.ext.pydantic import PydanticPlugin
from apispec_plugins.webframeworks.flask import FlaskPlugin
from flask import Flask
from pydantic import BaseModel
# set APISpec plugins
spec = APISpec(
title="Pet Store",
version="1.0.0",
openapi_version="3.0.3",
info=dict(description="A minimal pet store API"),
plugins=(FlaskPlugin(), PydanticPlugin()),
)
# optional Flask support
app = Flask(__name__)
# optional pydantic support
class Pet(BaseModel, RegistryMixin):
id: Optional[int]
name: str
@app.route("/pet/<petId>")
def pet(petId):
"""Find pet by ID.
---
get:
parameters:
- in: path
name: petId
responses:
200:
description: display pet data
content:
application/json:
schema: Pet
"""
return f"Display pet with ID {petId}"
# register `path` for the Flask route
with app.test_request_context():
spec.path(view=pet)
Alternatively, to Flask routes, 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"))
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 project 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;
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-1.1.1-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 908ec5eae4eeb822c093685146c951924511c38ccaef9acda9be40cc738e5ba6 |
|
MD5 | b0209fcf8626808498874d44d751728c |
|
BLAKE2b-256 | 03750423f2e4f93e857388ec8008f96cba26e065ad7d3ee463f9b145c901227f |