class APISpec(apispec.APISpec):
"""API specification class
This class subclasses original APISpec. The parameters are the same.
It adds a FlaskPlugin and a MarshmallowPlugin to the list of plugins. And
it defines methods to register stuff in those plugins.
"""
def __init__(self, title, version, openapi_version, plugins=(), **options):
self.flask_plugin = FlaskPlugin()
self.ma_plugin = MarshmallowPlugin()
plugins = [self.flask_plugin, self.ma_plugin] + list(plugins)
openapi_major_version = int(openapi_version.split('.')[0])
if openapi_major_version < 3:
options.setdefault('produces', [
'application/json',
])
options.setdefault('consumes', [
'application/json',
])
super().__init__(
title=title,
version=version,
openapi_version=openapi_version,
plugins=plugins,
**options,
)
def register_converter(self, converter, conv_type, conv_format=None):
"""Register custom path parameter converter
:param BaseConverter converter: Converter.
Subclass of werkzeug's BaseConverter
:param str conv_type: Parameter type
:param str conv_format: Parameter format (optional)
"""
self.flask_plugin.register_converter(converter, conv_type, conv_format)
def register_field(self, field, *args):
"""Register custom Marshmallow field
Registering the Field class allows the Schema parser to set the proper
type and format when documenting parameters from Schema fields.
:param Field field: Marshmallow Field class
``*args`` can be:
- a pair of the form ``(type, format)`` to map to
- a core marshmallow field type (then that type's mapping is used)
"""
self.ma_plugin.map_to_openapi_type(*args)(field)
},
{
'name': 'Users-By-Email',
'description':
'Access information about users via the user\'s email'
},
{
'name': 'Roles',
'description': 'Access and update Roles in your organization.'
},
{
'name': 'Permissions',
'description':
'Access and update Permissions in your organization.'
},
],
servers=[{
'url': '//dev-api.solarforecastarbiter.org/',
'description': 'Development server'
}, {
'url': '//testing-api.solarforecastarbiter.org/',
'description': 'Testing server'
}, {
'url': '//api.solarforecastarbiter.org/',
'description': 'Production server'
}])
ma_plugin.map_to_openapi_type('string', 'url')(URLFor)
ma_plugin.map_to_openapi_type('string', 'url')(AbsoluteURLFor)
ma_plugin.map_to_openapi_type('object', None)(Hyperlinks)
schema_dict = {"allOf": ret.pop("allOf")}
elif len(all_of) == 1:
schema_dict = all_of[0]
else:
schema_dict = {}
else:
schema_dict = self.resolve_nested_schema(field.schema)
ret["type"] = "array"
ret["items"] = {}
if schema_dict:
ret["items"].update(schema_dict)
return ret
ma_plugin.converter.add_attribute_function(nestedrelated2properties)
ma_plugin.map_to_openapi_type(String)(APIUrl)
def populate_spec():
"""Builds out the global `spec` with info about our API.
This is pretty messy, and you'll probably want to make some tweaks
depending on what you want your spec to look like.
One challenge with Drowsy based APIs and Swagger is that the
optional ability to embed nested relationships is hard (impossible?)
to represent with Swagger. The result is swagger-ui traversing
ALL possible embeds for every endpoint, which can get pretty messy,
and involve some null values showing up for circular references.
"""
