Core API¶

apispec¶

Contains main apispec classes: APISpec and BasePlugin

class apispec.APISpec(title, version, openapi_version, plugins=(), **options)[source]¶

Stores metadata that describes a RESTful API using the OpenAPI specification.

Parameters

title (str) – API title
version (str) – API version
plugins (list|tuple) – Plugin instances. See https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#infoObject
openapi_version (str|OpenAPIVersion) – OpenAPI Specification version. Should be in the form ‘2.x’ or ‘3.x.x’ to comply with the OpenAPI standard.
options (dict) – Optional top-level keys See https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#openapi-object

clean_operations(operations)[source]¶

Ensure that all parameters with “in” equal to “path” are also required as required by the OpenAPI specification, as well as normalizing any references to global parameters. Also checks for invalid HTTP methods.

See https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#parameterObject.

Parameters: operations (dict) – Dict mapping status codes to operations

clean_parameters(parameters)[source]¶

Ensure that all parameters with “in” equal to “path” are also required as required by the OpenAPI specification, as well as normalizing any references to global parameters and checking for duplicates parameters

See https ://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#parameterObject.

Parameters: parameters (list) – List of parameters mapping

get_ref(obj_type, obj)[source]¶

Return object or reference

If obj is a dict, it is assumed to be a complete description and it is returned as is. Otherwise, it is assumed to be a reference name as string and the corresponding $ref string is returned.

Parameters

obj_type (str) – “parameter” or “response”
obj (dict|str) – parameter or response in dict form or as ref_id string

path(path=None, *, operations=None, summary=None, description=None, parameters=None, **kwargs)[source]¶

Add a new path object to the spec.

https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#path-item-object

Parameters

path (str|None) – URL path component
operations (dict|None) – describes the http methods and options for path
summary (str) – short summary relevant to all operations in this path
description (str) – long description relevant to all operations in this path
parameters (list|None) – list of parameters relevant to all operations in this path
kwargs (dict) – parameters used by any path helpers see register_path_helper()

tag(tag)[source]¶

Store information about a tag.

Parameters: tag (dict) – the dictionary storing information about the tag.

to_yaml()[source]¶: Render the spec to YAML. Requires PyYAML to be installed.

class apispec.BasePlugin[source]¶

Base class for APISpec plugin classes.

init_spec(spec)[source]¶

Initialize plugin with APISpec object

Parameters: spec (APISpec) – APISpec object this plugin instance is attached to

operation_helper(path=None, operations=None, **kwargs)[source]¶

May mutate operations.

Parameters

path (str) – Path to the resource
operations (dict) – A dict mapping HTTP methods to operation object. See https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#operationObject
kwargs (dict) – All additional keywords arguments sent to APISpec.path()

parameter_helper(parameter, **kwargs)[source]¶

May return parameter component description as a dict.

Parameters

parameter (dict) – Parameter fields
kwargs (dict) – All additional keywords arguments sent to APISpec.parameter()

path_helper(path=None, operations=None, parameters=None, **kwargs)[source]¶

May return a path as string and mutate operations dict and parameters list.

Parameters

path (str) – Path to the resource
operations (dict) – A dict mapping HTTP methods to operation object. See https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#operationObject
parameters (list) – A list of parameters objects or references for the path. See https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#parameterObject and https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#referenceObject
kwargs (dict) – All additional keywords arguments sent to APISpec.path()

Return value should be a string or None. If a string is returned, it is set as the path.

The last path helper returning a string sets the path value. Therefore, the order of plugin registration matters. However, generally, registering several plugins that return a path does not make sense.

response_helper(response, **kwargs)[source]¶

May return response component description as a dict.

Parameters

response (dict) – Response fields
kwargs (dict) – All additional keywords arguments sent to APISpec.response()

schema_helper(name, definition, **kwargs)[source]¶

May return definition as a dict.

Parameters

name (str) – Identifier by which schema may be referenced
definition (dict) – Schema definition
kwargs (dict) – All additional keywords arguments sent to APISpec.schema()

apispec.core¶

Core apispec classes and functions.

class apispec.core.Components(plugins, openapi_version)[source]¶

Stores OpenAPI components

Components are top-level fields in OAS v2. They became sub-fields of “components” top-level field in OAS v3.

example(name, component, **kwargs)[source]¶

Add an example which can be referenced

Parameters

name (str) – identifier by which example may be referenced.
component (dict) – example fields.

https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md#exampleObject

parameter(component_id, location, component=None, **kwargs)[source]¶

Add a parameter which can be referenced.

Parameters

param_id (str) – identifier by which parameter may be referenced.
location (str) – location of the parameter.
component (dict) – parameter fields.
kwargs (dict) – plugin-specific arguments

response(component_id, component=None, **kwargs)[source]¶

Add a response which can be referenced.

Parameters

component_id (str) – ref_id to use as reference
component (dict) – response fields
kwargs (dict) – plugin-specific arguments

schema(name, component=None, **kwargs)[source]¶

Add a new schema to the spec.

Parameters

name (str) – identifier by which schema may be referenced.
component (dict) – schema definition.

Note

If you are using apispec.ext.marshmallow, you can pass fields’ metadata as additional keyword arguments.

For example, to add enum and description to your field:

status = fields.String(
    required=True,
    enum=['open', 'closed'],
    description='Status (open or closed)',
)

https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#schemaObject

security_scheme(component_id, component)[source]¶

Add a security scheme which can be referenced.

Parameters

component_id (str) – component_id to use as reference
kwargs (dict) – security scheme fields

apispec.exceptions¶

Exception classes.

exception apispec.exceptions.APISpecError[source]¶: Base class for all apispec-related errors.

exception apispec.exceptions.DuplicateComponentNameError[source]¶: Raised when registering two components with the same name

exception apispec.exceptions.DuplicateParameterError[source]¶: Raised when registering a parameter already existing in a given scope

exception apispec.exceptions.InvalidParameterError[source]¶: Raised when parameter doesn’t contains required keys

exception apispec.exceptions.OpenAPIError[source]¶: Raised when a OpenAPI spec validation fails.

exception apispec.exceptions.PluginMethodNotImplementedError[source]¶: Raised when calling an unimplemented helper method in a plugin

apispec.utils¶

Various utilities for parsing OpenAPI operations from docstrings and validating against the OpenAPI spec.

class apispec.utils.OpenAPIVersion(openapi_version)[source]¶

OpenAPI version

Parameters: openapi_version (str|OpenAPIVersion) – OpenAPI version

Parses an OpenAPI version expressed as string. Provides shortcut to digits (major, minor, patch).

Example:

ver = OpenAPIVersion('3.0.2')
assert ver.major == 3
assert ver.minor == 0
assert ver.patch == 1
assert ver.vstring == '3.0.2'
assert str(ver) == '3.0.2'

apispec.utils.build_reference(component_type, openapi_major_version, component_name)[source]¶

Return path to reference

Parameters

component_type (str) – Component type (schema, parameter, response, security_scheme)
openapi_major_version (int) – OpenAPI major version (2 or 3)
component_name (str) – Name of component to reference

apispec.utils.dedent(content)[source]¶: Remove leading indent from a block of text. Used when generating descriptions from docstrings. Note that python’s textwrap.dedent doesn’t quite cut it, as it fails to dedent multiline docstrings that include unindented text on the initial line.

apispec.utils.deepupdate(original, update)[source]¶

Recursively update a dict.

Subdict’s won’t be overwritten but also updated.

apispec.utils.trim_docstring(docstring)[source]¶

Uniformly trims leading/trailing whitespace from docstrings.

Based on http://www.python.org/peps/pep-0257.html#handling-docstring-indentation

apispec.utils.validate_spec(spec)[source]¶

Validate the output of an APISpec object against the OpenAPI specification.

Note: Requires installing apispec with the [validation] extras.

pip install 'apispec[validation]'

Raise: apispec.exceptions.OpenAPIError if validation fails.