Core API

apispec

Contains main apispec classes: APISpec and BasePlugin

class apispec.APISpec(title: str, version: str, openapi_version: OpenAPIVersion | str, plugins: Sequence[BasePlugin] = (), **options: Any)

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 – Optional top-level keys See https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#openapi-object

path(path: str | None = None, *, operations: dict[str, Any] | None = None, summary: str | None = None, description: str | None = None, parameters: list[dict] | None = None, **kwargs: Any) → APISpec

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 – parameters used by any path helpers see register_path_helper()

tag(tag: dict) → APISpec

Store information about a tag.

Parameters:

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

to_yaml(yaml_dump_kwargs: Any | None = None) → str

Render the spec to YAML. Requires PyYAML to be installed.

Parameters:

yaml_dump_kwargs (dict) – Additional keyword arguments to pass to yaml.dump

class apispec.BasePlugin

Base class for APISpec plugin classes.

header_helper(header: dict, **kwargs: Any) → dict | None

May return header component description as a dict.

Parameters:

• header (dict) – Header fields

• kwargs – All additional keywords arguments sent to APISpec.header()

init_spec(spec: APISpec) → None

Initialize plugin with APISpec object

Parameters:

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

operation_helper(path: str | None = None, operations: dict | None = None, **kwargs: Any) → None

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 – All additional keywords arguments sent to APISpec.path()

parameter_helper(parameter: dict, **kwargs: Any) → dict | None

May return parameter component description as a dict.

Parameters:

• parameter (dict) – Parameter fields

• kwargs – All additional keywords arguments sent to APISpec.parameter()

path_helper(path: str | None = None, operations: dict | None = None, parameters: list[dict] | None = None, **kwargs: Any) → str | None

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 – 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: dict, **kwargs: Any) → dict | None

May return response component description as a dict.

Parameters:

• response (dict) – Response fields

• kwargs – All additional keywords arguments sent to APISpec.response()

schema_helper(name: str, definition: dict, **kwargs: Any) → dict | None

May return definition as a dict.

Parameters:

• name (str) – Identifier by which schema may be referenced

• definition (dict) – Schema definition

• kwargs – All additional keywords arguments sent to APISpec.schema()

apispec.core

Core apispec classes and functions.

class apispec.core.Components(plugins: Sequence[BasePlugin], openapi_version: OpenAPIVersion)

Stores OpenAPI components

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

example(component_id: str, component: dict, *, lazy: bool = False) → Components

Add an example which can be referenced

Parameters:

• component_id (str) – identifier by which example may be referenced

• component (dict) – example fields

• lazy (bool) – register component only when referenced in the spec

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

get_ref(obj_type: str, obj_or_component_id: dict | str) → dict

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:

• subsection (str) – “schema”, “parameter”, “response” or “security_scheme”

• obj (dict|str) – object in dict form or as ref_id string

header(component_id: str, component: dict, *, lazy: bool = False, **kwargs: Any) → Components

Add a header which can be referenced.

Parameters:

• component_id (str) – identifier by which header may be referenced

• component (dict) – header fields

• lazy (bool) – register component only when referenced in the spec

• kwargs – plugin-specific arguments

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

parameter(component_id: str, location: str, component: dict | None = None, *, lazy: bool = False, **kwargs: Any) → Components

Add a parameter which can be referenced.

Parameters:

• component_id (str) – identifier by which parameter may be referenced

• location (str) – location of the parameter

• component (dict) – parameter fields

• lazy (bool) – register component only when referenced in the spec

• kwargs – plugin-specific arguments

response(component_id: str, component: dict | None = None, *, lazy: bool = False, **kwargs: Any) → Components

Add a response which can be referenced.

Parameters:

• component_id (str) – ref_id to use as reference

• component (dict) – response fields

• lazy (bool) – register component only when referenced in the spec

• kwargs – plugin-specific arguments

schema(component_id: str, component: dict | None = None, *, lazy: bool = False, **kwargs: Any) → Components

Add a new schema to the spec.

Parameters:

• component_id (str) – identifier by which schema may be referenced

• component (dict) – schema definition

• lazy (bool) – register component only when referenced in the spec

• kwargs – plugin-specific arguments

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,
    metadata={
        "description": "Status (open or closed)",
        "enum": ["open", "closed"],
    },
)

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

security_scheme(component_id: str, component: dict) → Components

Add a security scheme which can be referenced.

Parameters:

• component_id (str) – component_id to use as reference

• component (dict) – security scheme fields

apispec.exceptions

Exception classes.

exception apispec.exceptions.APISpecError

Base class for all apispec-related errors.

exception apispec.exceptions.DuplicateComponentNameError

Raised when registering two components with the same name

exception apispec.exceptions.DuplicateParameterError

Raised when registering a parameter already existing in a given scope

exception apispec.exceptions.InvalidParameterError

Raised when parameter doesn’t contains required keys

exception apispec.exceptions.OpenAPIError

Raised when a OpenAPI spec validation fails.

exception apispec.exceptions.PluginMethodNotImplementedError

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: distutils.version.LooseVersion | str)

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: str, openapi_major_version: int, component_name: str) → dict[str, str]

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: str) → str

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: dict, update: dict) → dict

Recursively update a dict.

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

apispec.utils.trim_docstring(docstring: str) → str

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: APISpec) → bool

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.