Upgrading to Newer Releases¶
This section documents migration paths to new releases.
Upgrading to 5.0.0¶
Upgrading to 4.0.0¶
location is ignored in field metadata¶
location
parameter is ignored in Field
metadata. A Schema
can only
have a single location.
A Schema
with fields from different locations must be split into multiple
``Schema``s.
Upgrading to 3.0.0¶
Upgrading to 2.0.0¶
plugin helpers must accept extra **kwargs
¶
Since custom plugins helpers may define extra kwargs and those kwargs are passed
to all plugin helpers by APISpec.path
, all plugins should
accept unknown kwargs.
The example plugin below defines an additional func
argument and accepts extra
**kwargs
.
class MyPlugin(BasePlugin):
def path_helper(self, path, func, **kwargs):
"""Path helper that parses docstrings for operations. Adds a
``func`` parameter to `apispec.APISpec.path`.
"""
operations.update(load_operations_from_docstring(func.__doc__))
Components must be referenced by ID, not full path¶
While apispec 1.x would let the user reference components by path or ID, apispec 2.x only accepts references by ID.
# apispec<2.0.0
spec.path(
path="/gist/{gist_id}",
operations=dict(
get=dict(
responses={
"200": {
"content": {
"application/json": {"schema": {"$ref": "#/definitions/Gist"}}
}
}
}
)
),
)
# apispec>=2.0.0
spec.path(
path="/gist/{gist_id}",
operations=dict(
get=dict(
responses={"200": {"content": {"application/json": {"schema": "Gist"}}}}
)
),
)
References by ID are accepted by both apispec 1.x ad 2.x and are a better choice because they delegate the creation of the full component path to apispec. This allows more flexibility as apispec creates the component path according to the OpenAPI version.
Upgrading to 1.0.0¶
openapi_version
Is Required¶
openapi_version
no longer defaults to "2.0"
. It is now a
required argument.
spec = APISpec(
title="Swagger Petstore",
version="1.0.0",
openapi_version="2.0", # or "3.0.2"
plugins=[MarshmallowPlugin()],
)
Web Framework Plugins Packaged Separately¶
apispec.ext.flask
, apispec.ext.bottle
, and
apispec.ext.tornado
have been moved to a a separate package,
apispec-webframeworks.
If you use these plugins, install apispec-webframeworks
with
pip
:
$ pip install apispec-webframeworks
Then, update your imports:
# apispec<1.0.0
from apispec.ext.flask import FlaskPlugin
# apispec>=1.0.0
from apispec_webframeworks.flask import FlaskPlugin
YAML Support Is Optional¶
YAML functionality is now optional. To install with YAML support:
$ pip install 'apispec[yaml]'
You will need to do this if you use apispec-webframeworks
or call
APISpec.to_yaml
in your code.
Registering Entities¶
Methods for registering OAS entities are changed to the noun form for internal consistency and for consistency with OAS v3 terminology.
# apispec<1.0.0
spec.add_tag({"name": "Pet", "description": "Operations on pets"})
spec.add_path("/pets/", operations={...})
spec.definition("Pet", properties={...})
spec.add_parameter("PetID", "path", {...})
# apispec>=1.0.0
spec.tag({"name": "Pet", "description": "Operations on pets"})
spec.path("/pets/", operations={...})
spec.components.schema("Pet", {"properties": {...}})
spec.components.parameter("PetID", "path", {...})
Adding Additional Fields to Schemas¶
The extra_fields
parameter to schema
is removed. It is no longer
necessary. Pass all fields in to the component dict
.
# <1.0.0
spec.definition("Pet", schema=PetSchema, extra_fields={"discriminator": "name"})
# >=1.0.0
spec.components.schema("Pet", schema=PetSchema, component={"discriminator": "name"})
Nested Schemas Are Referenced¶
When using the MarshmallowPlugin
, nested Schema
classes are referenced (with "$ref"
) in the output spec.
By default, the name in the spec will be the class name with the “Schema” suffix
removed, e.g. fields.Nested(PetSchema())
-> "#components/schemas/Pet"
.
The ref
argument to fields.Nested is no
longer respected.
# apispec<1.0.0
class PetSchema(Schema):
owner = fields.Nested(
HumanSchema,
# `ref` has no effect in 1.0.0. Remove.
ref="#components/schemas/Human",
)
# apispec>=1.0.0
class PetSchema(Schema):
owner = fields.Nested(HumanSchema)
See also
This behavior is customizable. See Nested Schemas.