Core API¶
apispec¶
Contains main apispec classes: APISpec
and BasePlugin
- class apispec.APISpec(title: str, version: str, openapi_version: str, plugins: Sequence[BasePlugin] = (), **options: Any)[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) – 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 [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 – parameters used by any path helpers see
register_path_helper()
- class apispec.BasePlugin[source]¶
Base class for APISpec plugin classes.
- header_helper(header: dict, **kwargs: Any) dict | None [source]¶
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 [source]¶
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 [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#operationObjectkwargs – All additional keywords arguments sent to
APISpec.path()
- parameter_helper(parameter: dict, **kwargs: Any) dict | None [source]¶
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 [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#operationObjectparameters (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#referenceObjectkwargs – 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.
apispec.core¶
Core apispec classes and functions.
- class apispec.core.Components(plugins: Sequence[BasePlugin], openapi_version: 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(component_id: str, component: dict, *, lazy: bool = False) Components [source]¶
Add an example which can be referenced
- Parameters
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 [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.
- header(component_id: str, component: dict, *, lazy: bool = False, **kwargs: Any) Components [source]¶
Add a header which can be referenced.
- Parameters
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 [source]¶
Add a parameter which can be referenced.
- response(component_id: str, component: dict | None = None, *, lazy: bool = False, **kwargs: Any) Components [source]¶
Add a response which can be referenced.
- schema(component_id: str, component: dict | None = None, *, lazy: bool = False, **kwargs: Any) Components [source]¶
Add a new schema to the spec.
- Parameters
Note
If you are using
apispec.ext.marshmallow
, you can pass fields’ metadata as additional keyword arguments.For example, to add
enum
anddescription
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
apispec.exceptions¶
Exception classes.
- 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
apispec.utils¶
Various utilities for parsing OpenAPI operations from docstrings and validating against the OpenAPI spec.
- apispec.utils.build_reference(component_type: str, openapi_major_version: int, component_name: str) dict[str, str] [source]¶
Return path to reference
- apispec.utils.dedent(content: str) str [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: dict, update: dict) dict [source]¶
Recursively update a dict.
Subdict’s won’t be overwritten but also updated.
- apispec.utils.trim_docstring(docstring: str) str [source]¶
Uniformly trims leading/trailing whitespace from docstrings.
Based on http://www.python.org/peps/pep-0257.html#handling-docstring-indentation