Using Plugins¶
What is an apispec “plugin”?¶
An apispec plugin is an object that provides helper methods for generating OpenAPI entities from objects in your application.
A plugin may modify the behavior of APISpec methods so that they can take your application’s objects as input.
Enabling Plugins¶
To enable a plugin, pass an instance to the constructor of APISpec.
from apispec import APISpec
from apispec.ext.marshmallow import MarshmallowPlugin
spec = APISpec(
title="Gisty",
version="1.0.0",
openapi_version="3.0.2",
info=dict(description="A minimal gist API"),
plugins=[MarshmallowPlugin()],
)
Example: Flask and Marshmallow Plugins¶
The bundled marshmallow plugin (apispec.ext.marshmallow.MarshmallowPlugin)
provides helpers for generating OpenAPI schema and parameter objects from marshmallow schemas and fields.
The apispec-webframeworks package includes a Flask plugin with helpers for generating path objects from view functions.
Let’s recreate the spec from the Quickstart guide using these two plugins.
First, ensure that apispec-webframeworks is installed:
$ pip install apispec-webframeworks
Also, ensure that a compatible marshmallow version is used:
$ pip install -U apispec[marshmallow]
We can now use the marshmallow and Flask plugins.
from apispec import APISpec
from apispec.ext.marshmallow import MarshmallowPlugin
from apispec_webframeworks.flask import FlaskPlugin
spec = APISpec(
title="Gisty",
version="1.0.0",
openapi_version="3.0.2",
info=dict(description="A minimal gist API"),
plugins=[FlaskPlugin(), MarshmallowPlugin()],
)
Our application will have a marshmallow Schema for gists.
from marshmallow import Schema, fields
class GistParameter(Schema):
gist_id = fields.Int()
class GistSchema(Schema):
id = fields.Int()
content = fields.Str()
The marshmallow plugin allows us to pass this Schema to
spec.components.schema.
spec.components.schema("Gist", schema=GistSchema)
The schema is now added to the spec.
from pprint import pprint
pprint(spec.to_dict())
# {'components': {'parameters': {}, 'responses': {}, 'schemas': {}},
# 'info': {'description': 'A minimal gist API',
# 'title': 'Gisty',
# 'version': '1.0.0'},
# 'openapi': '3.0.2',
# 'paths': {},
# 'tags': []}
Our application will have a Flask route for the gist detail endpoint.
We’ll add some YAML in the docstring to add response information.
from flask import Flask
app = Flask(__name__)
# NOTE: Plugins may inspect docstrings to gather more information for the spec
@app.route("/gists/<gist_id>")
def gist_detail(gist_id):
"""Gist detail view.
---
get:
parameters:
- in: path
schema: GistParameter
responses:
200:
content:
application/json:
schema: GistSchema
"""
return "details about gist {}".format(gist_id)
The Flask plugin allows us to pass this view to spec.path.
# 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)
Our OpenAPI spec now looks like this:
pprint(spec.to_dict())
# {'components': {'parameters': {},
# 'responses': {},
# 'schemas': {'Gist': {'properties': {'content': {'type': 'string'},
# 'id': {'format': 'int32',
# 'type': 'integer'}},
# 'type': 'object'}}},
# 'info': {'description': 'A minimal gist API',
# 'title': 'Gisty',
# 'version': '1.0.0'},
# 'openapi': '3.0.2',
# 'paths': {'/gists/{gist_id}': {'get': {'parameters': [{'in': 'path',
# 'name': 'gist_id',
# 'required': True,
# 'schema': {'format': 'int32',
# 'type': 'integer'}}],
# 'responses': {200: {'content': {'application/json': {'schema': {'$ref': '#/components/schemas/Gist'}}}}}}}},
# 'tags': []}
If your API uses method-based dispatching, the process is similar. Note that the method no longer needs to be included in the docstring.
from flask.views import MethodView
class GistApi(MethodView):
def get(self):
"""Gist view
---
description: Get a gist
responses:
200:
content:
application/json:
schema: GistSchema
"""
pass
def post(self):
pass
method_view = GistApi.as_view("gist")
app.add_url_rule("/gist", view_func=method_view)
with app.test_request_context():
spec.path(view=method_view)
pprint(dict(spec.to_dict()["paths"]["/gist"]))
# {'get': {'description': 'get a gist',
# 'responses': {200: {'content': {'application/json': {'schema': {'$ref': '#/components/schemas/Gist'}}}}}},
# 'post': {}}
Marshmallow Plugin¶
Nested Schemas¶
By default, Marshmallow Nested fields are represented by a JSON Reference object.
If the schema has been added to the spec via spec.components.schema,
the user-supplied name will be used in the reference. Otherwise apispec will
add the nested schema to the spec using an automatically resolved name for the
nested schema. The default resolver
function will resolve a name based on the schema’s class __name__, dropping a
trailing “Schema” so that class PetSchema(Schema) resolves to “Pet”.
To change the behavior of the name resolution simply pass a
function accepting a Schema class, Schema instance or a string that resolves
to a Schema class and returning a string to the plugin’s
constructor. To easily work with these argument types the marshmallow plugin provides
resolve_schema_cls
and resolve_schema_instance
functions. If the schema_name_resolver function returns a value that
evaluates to False in a boolean context the nested schema will not be added to
the spec and instead defined in-line.
Note
A schema_name_resolver function must return a string name when
working with circular-referencing schemas in order to avoid infinite
recursion.
Schema Modifiers¶
apispec will respect schema modifiers such as exclude and partial in the generated schema definition. If a schema is initialized with modifiers, apispec will treat each combination of modifiers as a unique schema definition.
Custom Fields¶
apispec maps standard marshmallow fields to OpenAPI types and formats. If your
custom field subclasses a standard marshmallow Field class then it will
inherit the default mapping. If you want to override the OpenAPI type and format
for custom fields, use the
map_to_openapi_type
method. It can be invoked with either a pair of strings providing the
OpenAPI type and format, or a marshmallow Field that has the desired target mapping.
from apispec import APISpec
from apispec.ext.marshmallow import MarshmallowPlugin
from marshmallow.fields import Integer, Field
ma_plugin = MarshmallowPlugin()
spec = APISpec(
title="Demo", version="0.1", openapi_version="3.0.0", plugins=(ma_plugin,)
)
# Inherits Integer mapping of ('integer', None)
class CustomInteger(Integer):
pass
# Override Integer mapping
class Int32(Integer):
pass
ma_plugin.map_to_openapi_type(Int32, "string", "int32")
# Map to ('integer', None) like Integer
class IntegerLike(Field):
pass
ma_plugin.map_to_openapi_type(IntegerLike, Integer)
In situations where greater control of the properties generated for a custom field
is desired, users may add custom logic to the conversion of fields to OpenAPI properties
through the use of the add_attribute_function
method. Continuing from the example above:
def my_custom_field2properties(self, field, **kwargs):
"""Add an OpenAPI extension flag to MyCustomField instances"""
ret = {}
if isinstance(field, MyCustomField):
if self.openapi_version.major > 2:
ret["x-customString"] = True
return ret
ma_plugin.converter.add_attribute_function(my_custom_field2properties)
The function passed to add_attribute_function will be bound to the converter.
It must accept the converter instance as first positional argument.
In some rare cases, typically with container fields such as fields derived from
List, documenting the parameters using this
field require some more customization.
This can be achieved using the add_parameter_attribute_function
method.
For instance, when documenting webargs’s
DelimitedList field, one may register
this function:
def delimited_list2param(self, field, **kwargs):
ret: dict = {}
if isinstance(field, DelimitedList):
if self.openapi_version.major < 3:
ret["collectionFormat"] = "csv"
else:
ret["explode"] = False
ret["style"] = "form"
return ret
ma_plugin.converter.add_parameter_attribute_function(delimited_list2param)
Next Steps¶
You now know how to use plugins. The next section will show you how to write plugins: Writing Plugins.