1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
|
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 :meth:`APISpec.path <APISpec.path>`, all plugins should
accept unknown kwargs.
The example plugin below defines an additional `func` argument and accepts extra
`**kwargs`.
.. code-block:: python
:emphasize-lines: 2
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.
.. code-block:: python
# 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.
.. code-block:: python
:emphasize-lines: 4
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 <https://github.com/marshmallow-code/apispec-webframeworks>`_.
If you use these plugins, install ``apispec-webframeworks`` with
``pip``:
::
$ pip install apispec-webframeworks
Then, update your imports:
.. code-block:: python
# 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 <apispec.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.
.. code-block:: python
# 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``.
.. code-block:: python
# <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
<apispec.ext.marshmallow.MarshmallowPlugin>`, nested `Schema
<marshmallow.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 <marshmallow.fields.Nested>`_ is no
longer respected.
.. code-block:: python
# 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)
.. seealso::
This behavior is customizable. See :ref:`marshmallow_nested_schemas`.
|
