Commit 15094bc3-43fa-437e-a299-1d90a33102b6/main - apispec

New upstream release. Kali Janitor 2 years ago

32 changed file(s) with 1335 addition(s) and 524 deletion(s). Raw diff Collapse all Expand all

-7

.pre-commit-config.yaml less more

0	0	repos:
1	1	- repo: https://github.com/asottile/pyupgrade
2		rev: v2.4.1
	2	rev: v2.11.0
3	3	hooks:
4	4	- id: pyupgrade
5		args: [--py3-plus]
	5	args: [--py36-plus]
6	6	- repo: https://github.com/python/black
7		rev: 19.10b0
	7	rev: 20.8b1
8	8	hooks:
9	9	- id: black
10	10	language_version: python3
11	11	- repo: https://gitlab.com/pycqa/flake8
12		rev: 3.8.1
	12	rev: 3.9.0
13	13	hooks:
14	14	- id: flake8
15		additional_dependencies: [flake8-bugbear==20.1.4]
	15	additional_dependencies: [flake8-bugbear==21.4.3]
16	16	- repo: https://github.com/asottile/blacken-docs
17		rev: v1.7.0
	17	rev: v1.10.0
18	18	hooks:
19	19	- id: blacken-docs
20		additional_dependencies: [black==19.10b0]
	20	additional_dependencies: [black==20.8b1]

-0

AUTHORS.rst less more

62	62	- Ashutosh Chaudhary `@codeasashu <https://github.com/codeasashu>`_
63	63	- Fedor Fominykh `@fedorfo <https://github.com/fedorfo>`_
64	64	- Colin Bounouar `@Colin-b <https://github.com/Colin-b>`_
	65	- Mikko Kortelainen `@kortsi <https://github.com/kortsi>`_
	66	- David Bishop `@teancom <https://github.com/teancom>`_
	67	- Andrea Ghensi `@sanzoghenzo <https://github.com/sanzoghenzo>`_
	68	- `@timsilvers <https://github.com/timsilvers>`_
	69	- Kangwook Lee `@pbzweihander <https://github.com/pbzweihander>`_
	70	- Martijn Pieters `@mjpieters <https://github.com/mjpieters>`_
	71	- Duncan Booth `@kupuguy <https://github.com/kupuguy>`_
	72	- Luke Whitehorn `<https://github.com/Anti-Distinctlyminty>`_
	73	- François Magimel `<https://github.com/Linkid>`_

+150

-1

CHANGELOG.rst less more

0	0	Changelog
1	1	---------
	2
	3	4.7.1 (2021-07-06)
	4	******************
	5
	6	Bug fixes:
	7
	8	- Correct spelling of 'null': remove extra quotes (:issue:`689`).
	9	Thanks :user:`mjpieters` for the PR.
	10
	11	4.7.0 (2021-06-28)
	12	******************
	13
	14	Features:
	15
	16	- Document `deprecated` property from field metadata (:pr:`686`).
	17	Thanks :user:`greyli` for the PR.
	18	- Document `writeOnly` and `nullable` properties from field metadata
	19	(:pr:`684`). Thanks :user:`greyli` for the PR.
	20
	21	4.6.0 (2021-06-14)
	22	******************
	23
	24	Features:
	25
	26	- Support `Pluck` field (:pr:`677`). Thanks :user:`mjpieters` for the PR.
	27	- Support `TimeDelta` field (:pr:`678`).
	28
	29	4.5.0 (2021-06-04)
	30	******************
	31
	32	Features:
	33
	34	- Support OpenAPI 3.1.0 (:issue:`579`).
	35
	36	Bug fixes:
	37
	38	- Fix `get_fields` to avoid crashing when a field is named `fields`
	39	(:issue:`673`). Thanks :user:`Reskov` for reporting.
	40
	41	Other changes:
	42
	43	- Don't pass field metadata as keyword arguments in the tests. This is
	44	deprecated since marshmallow 3.10. apispec is still compatible with
	45	marshmallow >=3,<3.10 but tests now require marshmallow >=3.10. (:pr:`675`)
	46
	47	4.4.2 (2021-05-24)
	48	******************
	49
	50	Bug fixes:
	51
	52	- Respect ``partial`` marshmallow schema parameter: don't document the field as
	53	required. (:issue:`627`). Thanks :user:`Anti-Distinctlyminty` for the PR.
	54
	55	4.4.1 (2021-05-07)
	56	******************
	57
	58	Bug fixes:
	59
	60	- Don't set ``additionalProperties`` if ``Meta.unknown`` is ``EXCLUDE``
	61	(:issue:`659`). Thanks :user:`kupuguy` for the PR.
	62
	63	4.4.0 (2021-03-31)
	64	******************
	65
	66	Features:
	67
	68	- Populate ``additionalProperties`` from ``Meta.unknown`` (:pr:`635`).
	69	Thanks :user:`timsilvers` for the PR.
	70	- Allow ``to_yaml`` to pass kwargs to ``yaml.dump`` (:pr:`648`).
	71	- Resolve header references in responses (:pr:`650`).
	72	- Resolve example references in parameters, request bodies and responses
	73	(:pr:`651`).
	74
	75	4.3.0 (2021-02-10)
	76	******************
	77
	78	Features:
	79
	80	- Add `apispec.core.Components.header` to register header components
	81	(:pr:`637`).
	82
	83	4.2.0 (2021-02-06)
	84	******************
	85
	86	Features:
	87
	88	- Make components public attributes of ``Components`` class (:pr:`634`).
	89
	90	4.1.0 (2021-01-26)
	91	******************
	92
	93	Features:
	94
	95	- Resolve schemas in callbacks (:pr:`544`). Thanks :user:`kortsi` for the PR.
	96
	97	Bug fixes:
	98
	99	- Fix docstrings documenting kwargs type as dict (:issue:`534`).
	100	- Use ``x-minimum`` and ``x-maximum`` extensions to document ranges that are
	101	not of number type (e.g. datetime) (:issue:`614`).
	102
	103	Other changes:
	104
	105	- Test against Python 3.9.
	106
	107	4.0.0 (2020-09-30)
	108	******************
	109
	110	Features:
	111
	112	- Backwards-incompatible: Automatically generate references for schemas
	113	passed as strings in responses and request bodies. When using
	114	``MarshmallowPlugin``, if a schema is passed as string, the marshmallow
	115	registry is looked up for this schema name and if none is found, the name is
	116	assumed to be a reference to a manually created schema and a reference is
	117	generated. No exception is raised anymore if the schema name can't be found
	118	in the registry. (:pr:`554`)
	119
	120	4.0.0b1 (2020-09-06)
	121	********************
	122
	123	Features:
	124
	125	- Backwards-incompatible: Ignore ``location`` field metadata. This attribute
	126	was used in webargs but it has now been dropped. A ``Schema`` can now only
	127	have a single location. This simplifies the logic in ``OpenAPIConverter``
	128	methods, where ``default_in`` argument now becomes ``location``. (:pr:`526`)
	129	- Backwards-incompatible: Don't document ``int`` format as ``"int32"`` and
	130	``float`` format as ``"float"``, as those are platform-dependent (:pr:`595`).
	131
	132	Refactoring:
	133
	134	- ``OpenAPIConverter.field2parameters`` and
	135	``OpenAPIConverter.property2parameter`` are removed.
	136	``OpenAPIConverter.field2parameter`` becomes private. (:pr:`581`)
	137
	138	Other changes:
	139
	140	- Drop support for marshmallow 2. Marshmallow 3.x is required. (:pr:`583`)
	141	- Drop support for Python 3.5. Python 3.6+ is required. (:pr:`582`)
	142
	143
	144	3.3.2 (2020-08-29)
	145	******************
	146
	147	Bug fixes:
	148
	149	- Fix crash when field metadata contains non-string keys (:pr:`596`).
	150	Thanks :user:`sanzoghenzo` for the fix.
2	151
3	152	3.3.1 (2020-06-06)
4	153	******************

8	157	- Fix ``MarshmallowPlugin`` crash when ``resolve_schema_dict`` is passed a
9	158	schema as string and ``schema_name_resolver`` returns ``None``
10	159	(:issue:`566`). Thanks :user:`black3r` for reporting and thanks
11		:user:`Bangterm` for the PR.
	160	:user:`Bangertm` for the PR.
12	161
13	162	3.3.0 (2020-02-14)
14	163	******************

+28

-2

README.rst less more

13	13	:target: https://apispec.readthedocs.io/
14	14	:alt: Documentation
15	15
16		.. image:: https://badgen.net/badge/marshmallow/2,3?list=1
	16	.. image:: https://badgen.net/badge/marshmallow/3?list=1
17	17	:target: https://marshmallow.readthedocs.io/en/latest/upgrading.html
18		:alt: marshmallow 2/3 compatible
	18	:alt: marshmallow 3 only
19	19
20	20	.. image:: https://badgen.net/badge/OAS/2,3?list=1&color=cyan
21	21	:target: https://github.com/OAI/OpenAPI-Specification

66	66	name = fields.Str()
67	67
68	68
	69	# Optional security scheme support
	70	api_key_scheme = {"type": "apiKey", "in": "header", "name": "X-API-Key"}
	71	spec.components.security_scheme("ApiKeyAuth", api_key_scheme)
	72
	73
69	74	# Optional Flask support
70	75	app = Flask(__name__)
71	76

76	81	---
77	82	get:
78	83	description: Get a random pet
	84	security:
	85	- ApiKeyAuth: []
79	86	responses:
80	87	200:
81	88	content:

104	111	# "/random": {
105	112	# "get": {
106	113	# "description": "Get a random pet",
	114	# "security": [
	115	# {
	116	# "ApiKeyAuth": []
	117	# }
	118	# ],
107	119	# "responses": {
108	120	# "200": {
109	121	# "content": {

157	169	# }
158	170	# }
159	171	# }
	172	# "securitySchemes": {
	173	# "ApiKeyAuth": {
	174	# "type": "apiKey",
	175	# "in": "header",
	176	# "name": "X-API-Key"
	177	# }
	178	# }
160	179	# }
161	180	# }
162	181	# }

179	198	# type: array
180	199	# name: {type: string}
181	200	# type: object
	201	# securitySchemes:
	202	# ApiKeyAuth:
	203	# in: header
	204	# name: X-API-KEY
	205	# type: apiKey
182	206	# info: {title: Swagger Petstore, version: 1.0.0}
183	207	# openapi: 3.0.2
184	208	# paths:

190	214	# content:
191	215	# application/json:
192	216	# schema: {$ref: '#/components/schemas/Pet'}
	217	# security:
	218	# - ApiKeyAuth: []
193	219	# tags: []
194	220
195	221

-11

azure-pipelines.yml less more

26	26	toxenvs:
27	27	- lint
28	28
29		- py35-marshmallow2
30		- py35-marshmallow3
	29	- py36-marshmallow3
	30	- py37-marshmallow3
	31	- py38-marshmallow3
	32	- py39-marshmallow3
31	33
32		- py36-marshmallow3
33
34		- py37-marshmallow3
35
36		- py38-marshmallow2
37		- py38-marshmallow3
38
39		- py38-marshmallowdev
	34	- py39-marshmallowdev
40	35
41	36	- docs
42	37	os: linux
43	38	- template: job--pypi-release.yml@sloria
44	39	parameters:
45		python: "3.8"
	40	python: "3.9"
46	41	distributions: "sdist bdist_wheel"
47	42	dependsOn:
48	43	- tox_linux

-0

debian/changelog less more

	0	apispec (4.7.1-0kali1) UNRELEASED; urgency=low
	1
	2	* New upstream release.
	3
	4	-- Kali Janitor <[email protected]> Tue, 27 Jul 2021 10:36:33 -0000
	5
0	6	apispec (3.3.1-0kali2) kali-dev; urgency=medium
1	7
2	8	[ Sophie Brun ]

-1

docs/conf.py less more

25	25	source_suffix = ".rst"
26	26	master_doc = "index"
27	27	project = "apispec"
28		copyright = "Steven Loria {:%Y}".format(dt.datetime.utcnow())
	28	copyright = f"Steven Loria {dt.datetime.utcnow():%Y}"
29	29
30	30	version = release = apispec.__version__
31	31

+27

-1

docs/index.rst less more

46	46	name = fields.Str()
47	47
48	48
	49	# Optional security scheme support
	50	api_key_scheme = {"type": "apiKey", "in": "header", "name": "X-API-Key"}
	51	spec.components.security_scheme("ApiKeyAuth", api_key_scheme)
	52
	53
49	54	# Optional Flask support
50	55	app = Flask(__name__)
51	56

56	61	---
57	62	get:
58	63	description: Get a random pet
	64	security:
	65	- ApiKeyAuth: []
59	66	responses:
60	67	200:
61	68	description: Return a pet

120	127	# "type": "string"
121	128	# }
122	129	# }
123		# }
	130	# },
	131	# }
	132	# },
	133	# "securitySchemes": {
	134	# "ApiKeyAuth": {
	135	# "type": "apiKey",
	136	# "in": "header",
	137	# "name": "X-API-Key"
124	138	# }
125	139	# },
126	140	# "paths": {
127	141	# "/random": {
128	142	# "get": {
129	143	# "description": "Get a random pet",
	144	# "security": [
	145	# {
	146	# "ApiKeyAuth": []
	147	# }
	148	# ],
130	149	# "responses": {
131	150	# "200": {
132	151	# "description": "Return a pet",

170	189	# name:
171	190	# type: string
172	191	# type: object
	192	# securitySchemes:
	193	# ApiKeyAuth:
	194	# in: header
	195	# name: X-API-KEY
	196	# type: apiKey
173	197	# paths:
174	198	# /random:
175	199	# get:

181	205	# schema:
182	206	# $ref: '#/components/schemas/Pet'
183	207	# description: Return a pet
	208	# security:
	209	# - ApiKeyAuth: []
184	210
185	211	User Guide
186	212	==========

-1

docs/install.rst less more

0	0	Install
1	1	=======
2	2
3		apispec requires Python >= 3.5.
	3	apispec requires Python >= 3.6.
4	4
5	5	From the PyPI
6	6	-------------

-2

docs/using_plugins.rst less more

279	279	.. code-block:: python
280	280
281	281	def my_custom_field2properties(self, field, **kwargs):
282		"""Add an OpenAPI extension flag to MyCustomField instances
283		"""
	282	"""Add an OpenAPI extension flag to MyCustomField instances"""
284	283	ret = {}
285	284	if isinstance(field, MyCustomField):
286	285	if self.openapi_version.major > 2:

-6

docs/writing_plugins.rst less more

24	24	.. code-block:: python
25	25
26	26	from apispec import Path, BasePlugin
27		from apispec.utils import load_operations_from_docstring
	27	from apispec.yaml_utils import load_operations_from_docstring
28	28
29	29
30	30	class MyPlugin(BasePlugin):
31		def path_helper(self, path, func, **kwargs):
	31	def path_helper(self, path, operations, func, **kwargs):
32	32	"""Path helper that parses docstrings for operations. Adds a
33	33	``func`` parameter to `apispec.APISpec.path`.
34	34	"""
35		operations = load_operations_from_docstring(func.__doc__)
36		return Path(path=path, operations=operations)
	35	operations.update(load_operations_from_docstring(func.__doc__))
37	36
38	37
39	38	All plugin helpers must accept extra `**kwargs`, allowing custom plugins to define new arguments if required.

50	49
51	50	class DeprecatedPlugin(BasePlugin):
52	51	def operation_helper(self, path, operations, **kwargs):
53		"""Operation helper that add `deprecated` flag if in `kwargs`
54		"""
	52	"""Operation helper that add `deprecated` flag if in `kwargs`"""
55	53	if kwargs.pop("deprecated", False) is True:
56	54	for key, value in operations.items():
57	55	value["deprecated"] = True

-0

pyproject.toml less more

	0	[tool.black]
	1	line-length = 88
	2	target-version = ['py36', 'py37', 'py38']

-9

setup.py less more

3	3	EXTRAS_REQUIRE = {
4	4	"yaml": ["PyYAML>=3.10"],
5	5	"validation": ["prance[osv]>=0.11"],
6		"lint": ["flake8==3.8.2", "flake8-bugbear==20.1.4", "pre-commit~=2.4"],
	6	"lint": ["flake8==3.9.2", "flake8-bugbear==21.4.3", "pre-commit~=2.4"],
7	7	"docs": [
8		"marshmallow>=2.19.2",
9		"pyyaml==5.3.1",
10		"sphinx==3.0.4",
	8	"marshmallow>=3.0.0",
	9	"pyyaml==5.4.1",
	10	"sphinx==4.0.3",
11	11	"sphinx-issues==1.2.0",
12		"sphinx-rtd-theme==0.4.3",
	12	"sphinx-rtd-theme==0.5.2",
13	13	],
14	14	}
15	15	EXTRAS_REQUIRE["tests"] = (
16	16	EXTRAS_REQUIRE["yaml"]
17	17	+ EXTRAS_REQUIRE["validation"]
18		+ ["marshmallow>=2.19.2", "pytest", "mock"]
	18	+ ["marshmallow>=3.10.0", "pytest", "mock"]
19	19	)
20	20	EXTRAS_REQUIRE["dev"] = EXTRAS_REQUIRE["tests"] + EXTRAS_REQUIRE["lint"] + ["tox"]
21	21

59	59	license="MIT",
60	60	zip_safe=False,
61	61	keywords="apispec swagger openapi specification oas documentation spec rest api",
62		python_requires=">=3.5",
	62	python_requires=">=3.6",
63	63	classifiers=[
64	64	"License :: OSI Approved :: MIT License",
65	65	"Programming Language :: Python :: 3",
66		"Programming Language :: Python :: 3.5",
67	66	"Programming Language :: Python :: 3.6",
68	67	"Programming Language :: Python :: 3.7",
69	68	"Programming Language :: Python :: 3.8",
	69	"Programming Language :: Python :: 3.9",
70	70	"Programming Language :: Python :: 3 :: Only",
71	71	],
72	72	test_suite="tests",
73	73	project_urls={
74	74	"Funding": "https://opencollective.com/marshmallow",
75	75	"Issues": "https://github.com/marshmallow-code/apispec/issues",
76		"Tidelift": "https://tidelift.com/subscription/pkg/pypi-apispec?utm_source=pypi-apispec&utm_medium=pypi", # noqa: E501
	76	"Tidelift": "https://tidelift.com/subscription/pkg/pypi-apispec?utm_source=pypi-apispec&utm_medium=pypi", # noqa: B950,E501
77	77	},
78	78	)

-1

src/apispec/__init__.py less more

2	2	from .core import APISpec
3	3	from .plugin import BasePlugin
4	4
5		__version__ = "3.3.1"
	5	__version__ = "4.7.1"
6	6	__all__ = ["APISpec", "BasePlugin"]

+101

-48

src/apispec/core.py less more

28	28	def __init__(self, plugins, openapi_version):
29	29	self._plugins = plugins
30	30	self.openapi_version = openapi_version
31		self._schemas = {}
32		self._responses = {}
33		self._parameters = {}
34		self._examples = {}
35		self._security_schemes = {}
	31	self.schemas = {}
	32	self.responses = {}
	33	self.parameters = {}
	34	self.headers = {}
	35	self.examples = {}
	36	self.security_schemes = {}
36	37
37	38	def to_dict(self):
38	39	subsections = {
39		"schema": self._schemas,
40		"response": self._responses,
41		"parameter": self._parameters,
42		"example": self._examples,
43		"security_scheme": self._security_schemes,
	40	"schema": self.schemas,
	41	"response": self.responses,
	42	"parameter": self.parameters,
	43	"header": self.headers,
	44	"example": self.examples,
	45	"security_scheme": self.security_schemes,
44	46	}
45	47	return {
46	48	COMPONENT_SUBSECTIONS[self.openapi_version.major][k]: v

63	65
64	66	status = fields.String(
65	67	required=True,
66		enum=['open', 'closed'],
67		description='Status (open or closed)',
	68	metadata={
	69	"description": "Status (open or closed)",
	70	"enum": ["open", "closed"],
	71	},
68	72	)
69	73
70	74	https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#schemaObject
71	75	"""
72		if name in self._schemas:
73		raise DuplicateComponentNameError(
74		'Another schema with name "{}" is already registered.'.format(name)
	76	if name in self.schemas:
	77	raise DuplicateComponentNameError(
	78	f'Another schema with name "{name}" is already registered.'
75	79	)
76	80	component = component or {}
77	81	ret = component.copy()

81	85	ret.update(plugin.schema_helper(name, component, **kwargs) or {})
82	86	except PluginMethodNotImplementedError:
83	87	continue
84		self._schemas[name] = ret
	88	self.schemas[name] = ret
85	89	return self
86	90
87	91	def response(self, component_id, component=None, **kwargs):

89	93
90	94	:param str component_id: ref_id to use as reference
91	95	:param dict component: response fields
92		:param dict kwargs: plugin-specific arguments
93		"""
94		if component_id in self._responses:
	96	:param kwargs: plugin-specific arguments
	97	"""
	98	if component_id in self.responses:
95	99	raise DuplicateComponentNameError(
96	100	'Another response with name "{}" is already registered.'.format(
97	101	component_id

105	109	ret.update(plugin.response_helper(component, **kwargs) or {})
106	110	except PluginMethodNotImplementedError:
107	111	continue
108		self._responses[component_id] = ret
	112	self.responses[component_id] = ret
109	113	return self
110	114
111	115	def parameter(self, component_id, location, component=None, **kwargs):
112		""" Add a parameter which can be referenced.
113
114		:param str param_id: identifier by which parameter may be referenced.
	116	"""Add a parameter which can be referenced.
	117
	118	:param str component_id: identifier by which parameter may be referenced.
115	119	:param str location: location of the parameter.
116	120	:param dict component: parameter fields.
117		:param dict kwargs: plugin-specific arguments
118		"""
119		if component_id in self._parameters:
	121	:param kwargs: plugin-specific arguments
	122	"""
	123	if component_id in self.parameters:
120	124	raise DuplicateComponentNameError(
121	125	'Another parameter with name "{}" is already registered.'.format(
122	126	component_id

137	141	ret.update(plugin.parameter_helper(component, **kwargs) or {})
138	142	except PluginMethodNotImplementedError:
139	143	continue
140		self._parameters[component_id] = ret
	144	self.parameters[component_id] = ret
	145	return self
	146
	147	def header(self, component_id, component):
	148	"""Add a header which can be referenced.
	149
	150	:param str component_id: identifier by which header may be referenced.
	151	:param dict component: header fields.
	152
	153	https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md#headerObject
	154	"""
	155	if component_id in self.headers:
	156	raise DuplicateComponentNameError(
	157	f'Another header with name "{component_id}" is already registered.'
	158	)
	159	self.headers[component_id] = component
141	160	return self
142	161
143	162	def example(self, name, component, **kwargs):

148	167
149	168	https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md#exampleObject
150	169	"""
151		if name in self._examples:
152		raise DuplicateComponentNameError(
153		'Another example with name "{}" is already registered.'.format(name)
154		)
155		self._examples[name] = component
	170	if name in self.examples:
	171	raise DuplicateComponentNameError(
	172	f'Another example with name "{name}" is already registered.'
	173	)
	174	self.examples[name] = component
156	175	return self
157	176
158	177	def security_scheme(self, component_id, component):
159	178	"""Add a security scheme which can be referenced.
160	179
161	180	:param str component_id: component_id to use as reference
162		:param dict kwargs: security scheme fields
163		"""
164		if component_id in self._security_schemes:
	181	:param dict component: security scheme fields
	182	"""
	183	if component_id in self.security_schemes:
165	184	raise DuplicateComponentNameError(
166	185	'Another security scheme with name "{}" is already registered.'.format(
167	186	component_id
168	187	)
169	188	)
170		self._security_schemes[component_id] = component
	189	self.security_schemes[component_id] = component
171	190	return self
172	191
173	192

180	199	See https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#infoObject
181	200	:param str\|OpenAPIVersion openapi_version: OpenAPI Specification version.
182	201	Should be in the form '2.x' or '3.x.x' to comply with the OpenAPI standard.
183		:param dict options: Optional top-level keys
	202	:param options: Optional top-level keys
184	203	See https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#openapi-object
185	204	"""
186	205

220	239	ret = deepupdate(ret, self.options)
221	240	return ret
222	241
223		def to_yaml(self):
224		"""Render the spec to YAML. Requires PyYAML to be installed."""
	242	def to_yaml(self, yaml_dump_kwargs=None):
	243	"""Render the spec to YAML. Requires PyYAML to be installed.
	244
	245	:param dict yaml_dump_kwargs: Additional keyword arguments to pass to `yaml.dump`
	246	"""
225	247	from .yaml_utils import dict_to_yaml
226	248
227		return dict_to_yaml(self.to_dict())
	249	return dict_to_yaml(self.to_dict(), yaml_dump_kwargs)
228	250
229	251	def tag(self, tag):
230		""" Store information about a tag.
	252	"""Store information about a tag.
231	253
232	254	:param dict tag: the dictionary storing information about the tag.
233	255	"""

242	264	summary=None,
243	265	description=None,
244	266	parameters=None,
245		**kwargs
	267	**kwargs,
246	268	):
247	269	"""Add a new path object to the spec.
248	270

253	275	:param str summary: short summary relevant to all operations in this path
254	276	:param str description: long description relevant to all operations in this path
255	277	:param list\|None parameters: list of parameters relevant to all operations in this path
256		:param dict kwargs: parameters used by any path helpers see :meth:`register_path_helper`
	278	:param kwargs: parameters used by any path helpers see :meth:`register_path_helper`
257	279	"""
258	280	# operations and parameters must be deepcopied because they are mutated
259	281	# in clean_operations and operation helpers and path may be called twice

299	321	Otherwise, it is assumed to be a reference name as string and the corresponding $ref
300	322	string is returned.
301	323
302		:param str obj_type: "parameter" or "response"
303		:param dict\|str obj: parameter or response in dict form or as ref_id string
	324	:param str obj_type: "schema", "parameter", "response" or "security_scheme"
	325	:param dict\|str obj: object in dict form or as ref_id string
304	326	"""
305	327	if isinstance(obj, dict):
306	328	return obj
307	329	return build_reference(obj_type, self.openapi_version.major, obj)
	330
	331	def _resolve_schema(self, obj):
	332	"""Replace schema reference as string with a $ref if needed."""
	333	if not isinstance(obj, dict):
	334	return
	335	if self.openapi_version.major < 3:
	336	if "schema" in obj:
	337	obj["schema"] = self.get_ref("schema", obj["schema"])
	338	else:
	339	if "content" in obj:
	340	for content in obj["content"].values():
	341	if "schema" in content:
	342	content["schema"] = self.get_ref("schema", content["schema"])
	343
	344	def _resolve_examples(self, obj):
	345	"""Replace example reference as string with a $ref"""
	346	for name, example in obj.get("examples", {}).items():
	347	obj["examples"][name] = self.get_ref("example", example)
308	348
309	349	def clean_parameters(self, parameters):
310	350	"""Ensure that all parameters with "in" equal to "path" are also required

322	362	missing_attrs = [attr for attr in ("name", "in") if attr not in parameter]
323	363	if missing_attrs:
324	364	raise InvalidParameterError(
325		"Missing keys {} for parameter".format(missing_attrs)
	365	f"Missing keys {missing_attrs} for parameter"
326	366	)
327	367
328	368	# OpenAPI Spec 3 and 2 don't allow for duplicated parameters

340	380	if parameter["in"] == "path":
341	381	parameter["required"] = True
342	382
	383	self._resolve_examples(parameter)
	384
343	385	return [self.get_ref("parameter", p) for p in parameters]
344	386
345	387	def clean_operations(self, operations):

364	406	for operation in (operations or {}).values():
365	407	if "parameters" in operation:
366	408	operation["parameters"] = self.clean_parameters(operation["parameters"])
	409	# OAS 3
	410	if "requestBody" in operation:
	411	self._resolve_schema(operation["requestBody"])
	412	for media_type in operation["requestBody"]["content"].values():
	413	self._resolve_examples(media_type)
	414
367	415	if "responses" in operation:
368	416	responses = OrderedDict()
369	417	for code, response in operation["responses"].items():

372	420	except (TypeError, ValueError):
373	421	if self.openapi_version.major < 3 and code != "default":
374	422	warnings.warn("Non-integer code not allowed in OpenAPI < 3")
375
376		responses[str(code)] = self.get_ref("response", response)
	423	self._resolve_schema(response)
	424	response = self.get_ref("response", response)
	425	for name, header in response.get("headers", {}).items():
	426	response["headers"][name] = self.get_ref("header", header)
	427	for media_type in response.get("content", {}).values():
	428	self._resolve_examples(media_type)
	429	responses[str(code)] = response
377	430	operation["responses"] = responses

-17

src/apispec/ext/marshmallow/__init__.py less more

47	47
48	48	class UserSchema(Schema):
49	49	id = fields.Int(dump_only=True)
50		name = fields.Str(description="The user's name")
	50	name = fields.Str(metadata={"description": "The user's name"})
51	51	created = fields.DateTime(
52		dump_only=True, default=dt.datetime.utcnow, doc_default="The current datetime"
	52	dump_only=True,
	53	default=dt.datetime.utcnow,
	54	metadata={"doc_default": "The current datetime"}
53	55	)
54	56
55	57

59	61	# 'format': 'date-time',
60	62	# 'readOnly': True,
61	63	# 'type': 'string'},
62		# 'id': {'format': 'int32',
63		# 'readOnly': True,
	64	# 'id': {'readOnly': True,
64	65	# 'type': 'integer'},
65	66	# 'name': {'description': "The user's name",
66	67	# 'type': 'string'}},

139	140	class MyCustomField(Integer):
140	141	# ...
141	142
142		@ma_plugin.map_to_openapi_type(Integer) # will map to ('integer', 'int32')
	143	@ma_plugin.map_to_openapi_type(Integer) # will map to ('integer', None)
143	144	class MyCustomFieldThatsKindaLikeAnInteger(Integer):
144	145	# ...
145	146	"""

187	188	return response
188	189
189	190	def operation_helper(self, operations, **kwargs):
190		for operation in operations.values():
191		if not isinstance(operation, dict):
192		continue
193		if "parameters" in operation:
194		operation["parameters"] = self.resolver.resolve_parameters(
195		operation["parameters"]
196		)
197		if self.openapi_version.major >= 3:
198		if "requestBody" in operation:
199		self.resolver.resolve_schema(operation["requestBody"])
200		for response in operation.get("responses", {}).values():
201		self.resolver.resolve_response(response)
	191	self.resolver.resolve_operations(operations)
202	192
203	193	def warn_if_schema_already_in_spec(self, schema_key):
204	194	"""Method to warn the user if the schema has already been added to the

+10

-22

src/apispec/ext/marshmallow/common.py less more

19	19	return schema()
20	20	if isinstance(schema, marshmallow.Schema):
21	21	return schema
22		try:
23		return marshmallow.class_registry.get_class(schema)()
24		except marshmallow.exceptions.RegistryError:
25		raise ValueError(
26		"{!r} is not a marshmallow.Schema subclass or instance and has not"
27		" been registered in the marshmallow class registry.".format(schema)
28		)
	22	return marshmallow.class_registry.get_class(schema)()
29	23
30	24
31	25	def resolve_schema_cls(schema):

38	32	return schema
39	33	if isinstance(schema, marshmallow.Schema):
40	34	return type(schema)
41		try:
42		return marshmallow.class_registry.get_class(schema)
43		except marshmallow.exceptions.RegistryError:
44		raise ValueError(
45		"{!r} is not a marshmallow.Schema subclass or instance and has not"
46		" been registered in the marshmallow class registry.".format(schema)
47		)
	35	return marshmallow.class_registry.get_class(schema)
48	36
49	37
50	38	def get_fields(schema, *, exclude_dump_only=False):

54	42	:param bool exclude_dump_only: whether to filter fields in Meta.dump_only
55	43	:rtype: dict, of field name field object pairs
56	44	"""
57		if hasattr(schema, "fields"):
	45	if isinstance(schema, marshmallow.Schema):
58	46	fields = schema.fields
59		elif hasattr(schema, "_declared_fields"):
	47	elif isinstance(schema, type) and issubclass(schema, marshmallow.Schema):
60	48	fields = copy.deepcopy(schema._declared_fields)
61	49	else:
62		raise ValueError(
63		"{!r} doesn't have either `fields` or `_declared_fields`.".format(schema)
64		)
	50	raise ValueError(f"{schema!r} is neither a Schema class nor a Schema instance.")
65	51	Meta = getattr(schema, "Meta", None)
66	52	warn_if_fields_defined_in_meta(fields, Meta)
67	53	return filter_excluded_fields(fields, Meta, exclude_dump_only=exclude_dump_only)

90	76
91	77	:param dict fields: A dictionary of fields name field object pairs
92	78	:param Meta: the schema's Meta class
93		:param bool exclude_dump_only: whether to filter fields in Meta.dump_only
	79	:param bool exclude_dump_only: whether to filter dump_only fields
94	80	"""
95	81	exclude = list(getattr(Meta, "exclude", []))
96	82	if exclude_dump_only:
97	83	exclude.extend(getattr(Meta, "dump_only", []))
98	84
99	85	filtered_fields = OrderedDict(
100		(key, value) for key, value in fields.items() if key not in exclude
	86	(key, value)
	87	for key, value in fields.items()
	88	if key not in exclude and not (exclude_dump_only and value.dump_only)
101	89	)
102	90
103	91	return filtered_fields

132	120	:param int counter: the counter of the number of recursions
133	121	:return: the unique name
134	122	"""
135		if name not in components._schemas:
	123	if name not in components.schemas:
136	124	return name
137	125	if not counter: # first time through recursion
138	126	warnings.warn(

+111

-58

src/apispec/ext/marshmallow/field_converter.py less more

16	16
17	17	RegexType = type(re.compile(""))
18	18
19		MARSHMALLOW_VERSION_INFO = tuple(
20		[int(part) for part in marshmallow.__version__.split(".") if part.isdigit()]
21		)
22
23
24	19	# marshmallow field => (JSON Schema type, format)
25	20	DEFAULT_FIELD_MAPPING = {
26		marshmallow.fields.Integer: ("integer", "int32"),
	21	marshmallow.fields.Integer: ("integer", None),
27	22	marshmallow.fields.Number: ("number", None),
28		marshmallow.fields.Float: ("number", "float"),
	23	marshmallow.fields.Float: ("number", None),
29	24	marshmallow.fields.Decimal: ("number", None),
30	25	marshmallow.fields.String: ("string", None),
31	26	marshmallow.fields.Boolean: ("boolean", None),

33	28	marshmallow.fields.DateTime: ("string", "date-time"),
34	29	marshmallow.fields.Date: ("string", "date"),
35	30	marshmallow.fields.Time: ("string", None),
	31	marshmallow.fields.TimeDelta: ("integer", None),
36	32	marshmallow.fields.Email: ("string", "email"),
37	33	marshmallow.fields.URL: ("string", "url"),
38	34	marshmallow.fields.Dict: ("object", None),

71	67	"properties",
72	68	"additionalProperties",
73	69	"readOnly",
	70	"writeOnly",
74	71	"xml",
75	72	"externalDocs",
76	73	"example",
	74	"nullable",
	75	"deprecated",
77	76	}
78	77
79	78

87	86
88	87	def init_attribute_functions(self):
89	88	self.attribute_functions = [
	89	# self.field2type_and_format should run first
	90	# as other functions may rely on its output
90	91	self.field2type_and_format,
91	92	self.field2default,
92	93	self.field2choices,

98	99	self.field2pattern,
99	100	self.metadata2properties,
100	101	self.nested2properties,
	102	self.pluck2properties,
101	103	self.list2properties,
102	104	self.dict2properties,
	105	self.timedelta2properties,
103	106	]
104	107
105	108	def map_to_openapi_type(self, *args):

211	214	else:
212	215	default = field.missing
213	216	if default is not marshmallow.missing and not callable(default):
214		if MARSHMALLOW_VERSION_INFO[0] >= 3:
215		default = field._serialize(default, None, None)
	217	default = field._serialize(default, None, None)
216	218	ret["default"] = default
217	219	return ret
218	220

264	266	attributes["writeOnly"] = True
265	267	return attributes
266	268
267		def field2nullable(self, field, **kwargs):
	269	def field2nullable(self, field, ret):
268	270	"""Return the dictionary of OpenAPI field attributes for a nullable field.
269	271
270	272	:param Field field: A marshmallow field.

272	274	"""
273	275	attributes = {}
274	276	if field.allow_none:
275		attributes[
276		"x-nullable" if self.openapi_version.major < 3 else "nullable"
277		] = True
	277	if self.openapi_version.major < 3:
	278	attributes["x-nullable"] = True
	279	elif self.openapi_version.minor < 1:
	280	attributes["nullable"] = True
	281	else:
	282	attributes["type"] = [*make_type_list(ret.get("type")), "null"]
278	283	return attributes
279	284
280		def field2range(self, field, **kwargs):
	285	def field2range(self, field, ret):
281	286	"""Return the dictionary of OpenAPI field attributes for a set of
282	287	:class:`Range <marshmallow.validators.Range>` validators.
283	288

294	299	)
295	300	]
296	301
297		attributes = {}
298		for validator in validators:
299		if validator.min is not None:
300		if hasattr(attributes, "minimum"):
301		attributes["minimum"] = max(attributes["minimum"], validator.min)
302		else:
303		attributes["minimum"] = validator.min
304		if validator.max is not None:
305		if hasattr(attributes, "maximum"):
306		attributes["maximum"] = min(attributes["maximum"], validator.max)
307		else:
308		attributes["maximum"] = validator.max
309		return attributes
	302	min_attr, max_attr = (
	303	("minimum", "maximum")
	304	if set(make_type_list(ret.get("type"))) & {"number", "integer"}
	305	else ("x-minimum", "x-maximum")
	306	)
	307	return make_min_max_attributes(validators, min_attr, max_attr)
310	308
311	309	def field2length(self, field, **kwargs):
312	310	"""Return the dictionary of OpenAPI field attributes for a set of

315	313	:param Field field: A marshmallow field.
316	314	:rtype: dict
317	315	"""
318		attributes = {}
319
320	316	validators = [
321	317	validator
322	318	for validator in field.validators

333	329	min_attr = "minItems" if is_array else "minLength"
334	330	max_attr = "maxItems" if is_array else "maxLength"
335	331
336		for validator in validators:
337		if validator.min is not None:
338		if hasattr(attributes, min_attr):
339		attributes[min_attr] = max(attributes[min_attr], validator.min)
340		else:
341		attributes[min_attr] = validator.min
342		if validator.max is not None:
343		if hasattr(attributes, max_attr):
344		attributes[max_attr] = min(attributes[max_attr], validator.max)
345		else:
346		attributes[max_attr] = validator.max
347
348		for validator in validators:
349		if validator.equal is not None:
350		attributes[min_attr] = validator.equal
351		attributes[max_attr] = validator.equal
352		return attributes
	332	equal_list = [
	333	validator.equal for validator in validators if validator.equal is not None
	334	]
	335	if equal_list:
	336	return {min_attr: equal_list[0], max_attr: equal_list[0]}
	337
	338	return make_min_max_attributes(validators, min_attr, max_attr)
353	339
354	340	def field2pattern(self, field, **kwargs):
355		"""Return the dictionary of OpenAPI field attributes for a set of
356		:class:`Range <marshmallow.validators.Regexp>` validators.
	341	"""Return the dictionary of OpenAPI field attributes for a
	342	:class:`Regexp <marshmallow.validators.Regexp>` validator.
	343
	344	If there is more than one such validator, only the first
	345	is used in the output spec.
357	346
358	347	:param Field field: A marshmallow field.
359	348	:rtype: dict

396	385	metadata = {
397	386	key.replace("_", "-") if key.startswith("x_") else key: value
398	387	for key, value in field.metadata.items()
	388	if isinstance(key, str)
399	389	}
400	390
401	391	# Avoid validation error with "Additional properties not allowed"

417	407	:param Field field: A marshmallow field.
418	408	:rtype: dict
419	409	"""
420		if isinstance(field, marshmallow.fields.Nested):
	410	# Pluck is a subclass of Nested but is in essence a single field; it
	411	# is treated separately by pluck2properties.
	412	if isinstance(field, marshmallow.fields.Nested) and not isinstance(
	413	field, marshmallow.fields.Pluck
	414	):
421	415	schema_dict = self.resolve_nested_schema(field.schema)
422	416	if ret and "$ref" in schema_dict:
423	417	ret.update({"allOf": [schema_dict]})

425	419	ret.update(schema_dict)
426	420	return ret
427	421
	422	def pluck2properties(self, field, **kwargs):
	423	"""Return a dictionary of properties from :class:`Pluck <marshmallow.fields.Pluck` fields.
	424
	425	Pluck effectively trans-includes a field from another schema into this,
	426	possibly wrapped in an array (`many=True`).
	427
	428	:param Field field: A marshmallow field.
	429	:rtype: dict
	430	"""
	431	if isinstance(field, marshmallow.fields.Pluck):
	432	plucked_field = field.schema.fields[field.field_name]
	433	ret = self.field2property(plucked_field)
	434	return {"type": "array", "items": ret} if field.many else ret
	435	return {}
	436
428	437	def list2properties(self, field, **kwargs):
429	438	"""Return a dictionary of properties from :class:`List <marshmallow.fields.List>` fields.
430	439

435	444	"""
436	445	ret = {}
437	446	if isinstance(field, marshmallow.fields.List):
438		inner_field = (
439		field.inner if MARSHMALLOW_VERSION_INFO[0] >= 3 else field.container
440		)
441		ret["items"] = self.field2property(inner_field)
	447	ret["items"] = self.field2property(field.inner)
442	448	return ret
443	449
444	450	def dict2properties(self, field, **kwargs):

452	458	"""
453	459	ret = {}
454	460	if isinstance(field, marshmallow.fields.Dict):
455		if MARSHMALLOW_VERSION_INFO[0] >= 3:
456		value_field = field.value_field
457		if value_field:
458		ret["additionalProperties"] = self.field2property(value_field)
459		return ret
	461	value_field = field.value_field
	462	if value_field:
	463	ret["additionalProperties"] = self.field2property(value_field)
	464	return ret
	465
	466	def timedelta2properties(self, field, **kwargs):
	467	"""Return a dictionary of properties from :class:`TimeDelta <marshmallow.fields.TimeDelta>` fields.
	468
	469	Adds a `x-unit` vendor property based on the field's `precision` attribute
	470
	471	:param Field field: A marshmallow field.
	472	:rtype: dict
	473	"""
	474	ret = {}
	475	if isinstance(field, marshmallow.fields.TimeDelta):
	476	ret["x-unit"] = field.precision
	477	return ret
	478
	479
	480	def make_type_list(types):
	481	"""Return a list of types from a type attribute
	482
	483	Since OpenAPI 3.1.0, "type" can be a single type as string or a list of
	484	types, including 'null'. This function takes a "type" attribute as input
	485	and returns it as a list, be it an empty or single-element list.
	486	This is useful to factorize type-conditional code or code adding a type.
	487	"""
	488	if types is None:
	489	return []
	490	if isinstance(types, str):
	491	return [types]
	492	return types
	493
	494
	495	def make_min_max_attributes(validators, min_attr, max_attr):
	496	"""Return a dictionary of minimum and maximum attributes based on a list
	497	of validators. If either minimum or maximum values are not present in any
	498	of the validator objects that attribute will be omitted.
	499
	500	:param validators list: A list of `Marshmallow` validator objects. Each
	501	objct is inspected for a minimum and maximum values
	502	:param min_attr string: The OpenAPI attribute for the minimum value
	503	:param max_attr string: The OpenAPI attribute for the maximum value
	504	"""
	505	attributes = {}
	506	min_list = [validator.min for validator in validators if validator.min is not None]
	507	max_list = [validator.max for validator in validators if validator.max is not None]
	508	if min_list:
	509	attributes[min_attr] = max(min_list)
	510	if max_list:
	511	attributes[max_attr] = min(max_list)
	512	return attributes

+48

-130

src/apispec/ext/marshmallow/openapi.py less more

18	18	make_schema_key,
19	19	resolve_schema_instance,
20	20	get_unique_schema_name,
21		)
22
23
24		MARSHMALLOW_VERSION_INFO = tuple(
25		[int(part) for part in marshmallow.__version__.split(".") if part.isdigit()]
26	21	)
27	22
28	23

59	54	# Schema references
60	55	self.refs = {}
61	56
62		@staticmethod
63		def _observed_name(field, name):
64		"""Adjust field name to reflect `dump_to` and `load_from` attributes.
65
66		:param Field field: A marshmallow field.
67		:param str name: Field name
68		:rtype: str
69		"""
70		if MARSHMALLOW_VERSION_INFO[0] < 3:
71		# use getattr in case we're running against older versions of marshmallow.
72		dump_to = getattr(field, "dump_to", None)
73		load_from = getattr(field, "load_from", None)
74		return dump_to or load_from or name
75		return field.data_key or name
76
77	57	def resolve_nested_schema(self, schema):
78	58	"""Return the OpenAPI representation of a marshmallow Schema.
79	59

86	66
87	67	:param schema: schema to add to the spec
88	68	"""
89		schema_instance = resolve_schema_instance(schema)
	69	try:
	70	schema_instance = resolve_schema_instance(schema)
	71	# If schema is a string and is not found in registry,
	72	# assume it is a schema reference
	73	except marshmallow.exceptions.RegistryError:
	74	return build_reference("schema", self.openapi_version.major, schema)
90	75	schema_key = make_schema_key(schema_instance)
91	76	if schema_key not in self.refs:
92	77	name = self.schema_name_resolver(schema)

109	94	return self.get_ref_dict(schema_instance)
110	95
111	96	def schema2parameters(
112		self,
113		schema,
114		*,
115		default_in="body",
116		name="body",
117		required=False,
118		description=None
	97	self, schema, *, location, name="body", required=False, description=None
119	98	):
120	99	"""Return an array of OpenAPI parameters given a given marshmallow
121		:class:`Schema <marshmallow.Schema>`. If `default_in` is "body", then return an array
	100	:class:`Schema <marshmallow.Schema>`. If `location` is "body", then return an array
122	101	of a single parameter; else return an array of a parameter for each included field in
123	102	the :class:`Schema <marshmallow.Schema>`.
124	103
	104	In OpenAPI 3, only "query", "header", "path" or "cookie" are allowed for the location
	105	of parameters. "requestBody" is used when fields are in the body.
	106
125	107	https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#parameterObject
126	108	"""
127		openapi_default_in = __location_map__.get(default_in, default_in)
128		if self.openapi_version.major < 3 and openapi_default_in == "body":
129		prop = self.resolve_nested_schema(schema)
130
	109	location = __location_map__.get(location, location)
	110	# OAS 2 body parameter
	111	if location == "body":
131	112	param = {
132		"in": openapi_default_in,
	113	"in": location,
133	114	"required": required,
134	115	"name": name,
135		"schema": prop,
	116	"schema": self.resolve_nested_schema(schema),
136	117	}
137
138	118	if description:
139	119	param["description"] = description
140
141	120	return [param]
142	121
143	122	assert not getattr(

146	125
147	126	fields = get_fields(schema, exclude_dump_only=True)
148	127
149		return self.fields2parameters(fields, default_in=default_in)
150
151		def fields2parameters(self, fields, *, default_in):
152		"""Return an array of OpenAPI parameters given a mapping between field names and
153		:class:`Field <marshmallow.Field>` objects. If `default_in` is "body", then return an array
154		of a single parameter; else return an array of a parameter for each included field in
155		the :class:`Schema <marshmallow.Schema>`.
156
157		In OpenAPI3, only "query", "header", "path" or "cookie" are allowed for the location
158		of parameters. In OpenAPI 3, "requestBody" is used when fields are in the body.
159
160		This function always returns a list, with a parameter
161		for each included field in the :class:`Schema <marshmallow.Schema>`.
162
163		https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#parameterObject
164		"""
165		parameters = []
166		body_param = None
167		for field_name, field_obj in fields.items():
168		if field_obj.dump_only:
169		continue
170		param = self.field2parameter(
	128	return [
	129	self._field2parameter(
171	130	field_obj,
172		name=self._observed_name(field_obj, field_name),
173		default_in=default_in,
	131	name=field_obj.data_key or field_name,
	132	location=location,
174	133	)
175		if (
176		self.openapi_version.major < 3
177		and param["in"] == "body"
178		and body_param is not None
179		):
180		body_param["schema"]["properties"].update(param["schema"]["properties"])
181		required_fields = param["schema"].get("required", [])
182		if required_fields:
183		body_param["schema"].setdefault("required", []).extend(
184		required_fields
185		)
186		else:
187		if self.openapi_version.major < 3 and param["in"] == "body":
188		body_param = param
189		parameters.append(param)
190		return parameters
191
192		def field2parameter(self, field, *, name, default_in):
	134	for field_name, field_obj in fields.items()
	135	]
	136
	137	def _field2parameter(self, field, *, name, location):
193	138	"""Return an OpenAPI parameter as a `dict`, given a marshmallow
194	139	:class:`Field <marshmallow.Field>`.
195	140
196	141	https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#parameterObject
197	142	"""
198		location = field.metadata.get("location", None)
	143	ret = {"in": location, "name": name}
	144
	145	partial = getattr(field.parent, "partial", False)
	146	ret["required"] = field.required and (
	147	not partial or (is_collection(partial) and field.name not in partial)
	148	)
	149
199	150	prop = self.field2property(field)
200		return self.property2parameter(
201		prop,
202		name=name,
203		required=field.required,
204		multiple=isinstance(field, marshmallow.fields.List),
205		location=location,
206		default_in=default_in,
207		)
208
209		def property2parameter(
210		self, prop, *, name, required, multiple, location, default_in
211		):
212		"""Return the Parameter Object definition for a JSON Schema property.
213
214		https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#parameterObject
215
216		:param dict prop: JSON Schema property
217		:param str name: Field name
218		:param bool required: Parameter is required
219		:param bool multiple: Parameter is repeated
220		:param str location: Location to look for ``name``
221		:param str default_in: Default location to look for ``name``
222		:raise: TranslationError if arg object cannot be translated to a Parameter Object schema.
223		:rtype: dict, a Parameter Object
224		"""
225		openapi_default_in = __location_map__.get(default_in, default_in)
226		openapi_location = __location_map__.get(location, openapi_default_in)
227		ret = {"in": openapi_location, "name": name}
228
229		if openapi_location == "body":
230		ret["required"] = False
231		ret["name"] = "body"
232		ret["schema"] = {"type": "object", "properties": {name: prop}}
233		if required:
234		ret["schema"]["required"] = [name]
	151	multiple = isinstance(field, marshmallow.fields.List)
	152
	153	if self.openapi_version.major < 3:
	154	if multiple:
	155	ret["collectionFormat"] = "multi"
	156	ret.update(prop)
235	157	else:
236		ret["required"] = required
237		if self.openapi_version.major < 3:
238		if multiple:
239		ret["collectionFormat"] = "multi"
240		ret.update(prop)
241		else:
242		if multiple:
243		ret["explode"] = True
244		ret["style"] = "form"
245		if prop.get("description", None):
246		ret["description"] = prop.pop("description")
247		ret["schema"] = prop
	158	if multiple:
	159	ret["explode"] = True
	160	ret["style"] = "form"
	161	if prop.get("description", None):
	162	ret["description"] = prop.pop("description")
	163	ret["schema"] = prop
248	164	return ret
249	165
250	166	def schema2jsonschema(self, schema):

268	184	jsonschema["title"] = Meta.title
269	185	if hasattr(Meta, "description"):
270	186	jsonschema["description"] = Meta.description
	187	if hasattr(Meta, "unknown") and Meta.unknown != marshmallow.EXCLUDE:
	188	jsonschema["additionalProperties"] = Meta.unknown == marshmallow.INCLUDE
271	189
272	190	return jsonschema
273	191

285	203	jsonschema = {"type": "object", "properties": OrderedDict() if ordered else {}}
286	204
287	205	for field_name, field_obj in fields.items():
288		observed_field_name = self._observed_name(field_obj, field_name)
289		property = self.field2property(field_obj)
290		jsonschema["properties"][observed_field_name] = property
	206	observed_field_name = field_obj.data_key or field_name
	207	prop = self.field2property(field_obj)
	208	jsonschema["properties"][observed_field_name] = prop
291	209
292	210	if field_obj.required:
293	211	if not partial or (

+73

-4

src/apispec/ext/marshmallow/schema_resolver.py less more

14	14	self.openapi_version = openapi_version
15	15	self.converter = converter
16	16
	17	def resolve_operations(self, operations, **kwargs):
	18	"""Resolve marshmallow Schemas in a dict mapping operation to OpenApi `Operation Object
	19	https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#operationObject`_"""
	20
	21	for operation in operations.values():
	22	if not isinstance(operation, dict):
	23	continue
	24	if "parameters" in operation:
	25	operation["parameters"] = self.resolve_parameters(
	26	operation["parameters"]
	27	)
	28	if self.openapi_version.major >= 3:
	29	self.resolve_callback(operation.get("callbacks", {}))
	30	if "requestBody" in operation:
	31	self.resolve_schema(operation["requestBody"])
	32	for response in operation.get("responses", {}).values():
	33	self.resolve_response(response)
	34
	35	def resolve_callback(self, callbacks):
	36	"""Resolve marshmallow Schemas in a dict mapping callback name to OpenApi `Callback Object
	37	https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#callbackObject`_.
	38
	39	This is done recursively, so it is possible to define callbacks in your callbacks.
	40
	41	Example: ::
	42
	43	#Input
	44	{
	45	"userEvent": {
	46	"https://my.example/user-callback": {
	47	"post": {
	48	"requestBody": {
	49	"content": {
	50	"application/json": {
	51	"schema": UserSchema
	52	}
	53	}
	54	}
	55	},
	56	}
	57	}
	58	}
	59
	60	#Output
	61	{
	62	"userEvent": {
	63	"https://my.example/user-callback": {
	64	"post": {
	65	"requestBody": {
	66	"content": {
	67	"application/json": {
	68	"schema": {
	69	"$ref": "#/components/schemas/User"
	70	}
	71	}
	72	}
	73	}
	74	},
	75	}
	76	}
	77	}
	78
	79
	80	"""
	81	for callback in callbacks.values():
	82	if isinstance(callback, dict):
	83	for path in callback.values():
	84	self.resolve_operations(path)
	85
17	86	def resolve_parameters(self, parameters):
18	87	"""Resolve marshmallow Schemas in a list of OpenAPI `Parameter Objects
19	88	<https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#parameter-object>`_.

37	106
38	107	#Output
39	108	[
40		{"in": "query", "name": "id", "required": False, "schema": {"type": "integer", "format": "int32"}},
	109	{"in": "query", "name": "id", "required": False, "schema": {"type": "integer"}},
41	110	{"in": "query", "name": "name", "required": False, "schema": {"type": "string"}}
42	111	]
43	112

75	144	):
76	145	schema_instance = resolve_schema_instance(parameter.pop("schema"))
77	146	resolved += self.converter.schema2parameters(
78		schema_instance, default_in=parameter.pop("in"), **parameter
	147	schema_instance, location=parameter.pop("in"), **parameter
79	148	)
80	149	else:
81	150	self.resolve_schema(parameter)

161	230
162	231	def resolve_schema_dict(self, schema):
163	232	"""Resolve a marshmallow Schema class, object, or a string that resolves
164		to a Schema class or an OpenAPI Schema Object containing one of the above
165		to an OpenAPI Schema Object or Reference Object.
	233	to a Schema class or a schema reference or an OpenAPI Schema Object
	234	containing one of the above to an OpenAPI Schema Object or Reference Object.
166	235
167	236	If the input is a marshmallow Schema class, object or a string that resolves
168	237	to a Schema class the Schema will be translated to an OpenAPI Schema Object

-5

src/apispec/plugin.py less more

17	17
18	18	:param str name: Identifier by which schema may be referenced
19	19	:param dict definition: Schema definition
20		:param dict kwargs: All additional keywords arguments sent to `APISpec.schema()`
	20	:param kwargs: All additional keywords arguments sent to `APISpec.schema()`
21	21	"""
22	22	raise PluginMethodNotImplementedError
23	23

25	25	"""May return response component description as a dict.
26	26
27	27	:param dict response: Response fields
28		:param dict kwargs: All additional keywords arguments sent to `APISpec.response()`
	28	:param kwargs: All additional keywords arguments sent to `APISpec.response()`
29	29	"""
30	30	raise PluginMethodNotImplementedError
31	31

33	33	"""May return parameter component description as a dict.
34	34
35	35	:param dict parameter: Parameter fields
36		:param dict kwargs: All additional keywords arguments sent to `APISpec.parameter()`
	36	:param kwargs: All additional keywords arguments sent to `APISpec.parameter()`
37	37	"""
38	38	raise PluginMethodNotImplementedError
39	39

46	46	:param list parameters: A `list` of parameters objects or references for the path. See
47	47	https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#parameterObject
48	48	and https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#referenceObject
49		:param dict kwargs: All additional keywords arguments sent to `APISpec.path()`
	49	:param kwargs: All additional keywords arguments sent to `APISpec.path()`
50	50
51	51	Return value should be a string or None. If a string is returned, it
52	52	is set as the path.

63	63	:param str path: Path to the resource
64	64	:param dict operations: A `dict` mapping HTTP methods to operation object.
65	65	See https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#operationObject
66		:param dict kwargs: All additional keywords arguments sent to `APISpec.path()`
	66	:param kwargs: All additional keywords arguments sent to `APISpec.path()`
67	67	"""
68	68	raise PluginMethodNotImplementedError

-1

src/apispec/utils.py less more

19	19	"schema": "schemas",
20	20	"response": "responses",
21	21	"parameter": "parameters",
	22	"header": "headers",
22	23	"example": "examples",
23	24	"security_scheme": "securitySchemes",
24	25	},

102	103	< self.MAX_EXCLUSIVE_VERSION
103	104	):
104	105	raise exceptions.APISpecError(
105		"Not a valid OpenAPI version number: {}".format(openapi_version)
	106	f"Not a valid OpenAPI version number: {openapi_version}"
106	107	)
107	108	super().__init__(openapi_version)
108	109

-2

src/apispec/yaml_utils.py less more

14	14	yaml.add_representer(OrderedDict, YAMLDumper._represent_dict, Dumper=YAMLDumper)
15	15
16	16
17		def dict_to_yaml(dic):
18		return yaml.dump(dic, Dumper=YAMLDumper)
	17	def dict_to_yaml(dic, yaml_dump_kwargs=None):
	18	if yaml_dump_kwargs is None:
	19	yaml_dump_kwargs = {}
	20	return yaml.dump(dic, Dumper=YAMLDumper, **yaml_dump_kwargs)
19	21
20	22
21	23	def load_yaml_from_docstring(docstring):

+17

-17

tests/schemas.py less more

0	0	from marshmallow import Schema, fields
1
2		from apispec.ext.marshmallow.openapi import MARSHMALLOW_VERSION_INFO
3	1
4	2
5	3	class PetSchema(Schema):
6	4	description = dict(id="Pet id", name="Pet name", password="Password")
7		id = fields.Int(dump_only=True, description=description["id"])
	5	id = fields.Int(dump_only=True, metadata={"description": description["id"]})
8	6	name = fields.Str(
9	7	required=True,
10		deprecated=False,
11		allowEmptyValue=False,
12		description=description["name"],
	8	metadata={
	9	"description": description["name"],
	10	"deprecated": False,
	11	"allowEmptyValue": False,
	12	},
13	13	)
14		password = fields.Str(load_only=True, description=description["password"])
	14	password = fields.Str(
	15	load_only=True, metadata={"description": description["password"]}
	16	)
15	17
16	18
17	19	class SampleSchema(Schema):

33	35
34	36
35	37	class PatternedObjectSchema(Schema):
36		count = fields.Int(dump_only=True, **{"x-count": 1})
37		count2 = fields.Int(dump_only=True, x_count2=2)
	38	count = fields.Int(dump_only=True, metadata={"x-count": 1})
	39	count2 = fields.Int(dump_only=True, metadata={"x_count2": 2})
38	40
39	41
40	42	class SelfReferencingSchema(Schema):
41	43	id = fields.Int()
42		if MARSHMALLOW_VERSION_INFO[0] < 3:
43		single = fields.Nested("self")
44		many = fields.Nested("self", many=True)
45		else:
46		single = fields.Nested(lambda: SelfReferencingSchema())
47		many = fields.Nested(lambda: SelfReferencingSchema(many=True))
	44	single = fields.Nested(lambda: SelfReferencingSchema())
	45	many = fields.Nested(lambda: SelfReferencingSchema(many=True))
48	46
49	47
50	48	class OrderedSchema(Schema):

60	58
61	59	class DefaultValuesSchema(Schema):
62	60	number_auto_default = fields.Int(missing=12)
63		number_manual_default = fields.Int(missing=12, doc_default=42)
	61	number_manual_default = fields.Int(missing=12, metadata={"doc_default": 42})
64	62	string_callable_default = fields.Str(missing=lambda: "Callable")
65		string_manual_default = fields.Str(missing=lambda: "Callable", doc_default="Manual")
	63	string_manual_default = fields.Str(
	64	missing=lambda: "Callable", metadata={"doc_default": "Manual"}
	65	)
66	66	numbers = fields.List(fields.Int, missing=list)
67	67
68	68

+107

-4

tests/test_core.py less more

16	16	get_examples,
17	17	get_paths,
18	18	get_parameters,
	19	get_headers,
19	20	get_responses,
20	21	get_security_schemes,
21	22	build_ref,

59	60	version="1.0.0",
60	61	openapi_version=openapi_version,
61	62	info={"description": description},
62		**security_kwargs
	63	**security_kwargs,
63	64	)
64	65
65	66

201	202	spec.components.response("test_response")
202	203
203	204	def test_parameter(self, spec):
	205	# Note: this is an OpenAPI v2 parameter header
	206	# but is does the job for the test even for OpenAPI v3
204	207	parameter = {"format": "int64", "type": "integer"}
205	208	spec.components.parameter("PetId", "path", parameter)
206	209	params = get_parameters(spec)

225	228	match='Another parameter with name "test_parameter" is already registered.',
226	229	):
227	230	spec.components.parameter("test_parameter", "path")
	231
	232	# Referenced headers are only supported in OAS 3.x
	233	@pytest.mark.parametrize("spec", ("3.0.0",), indirect=True)
	234	def test_header(self, spec):
	235	header = {"schema": {"type": "string"}}
	236	spec.components.header("test_header", header.copy())
	237	headers = get_headers(spec)
	238	assert headers["test_header"] == header
	239
	240	# Referenced headers are only supported in OAS 3.x
	241	@pytest.mark.parametrize("spec", ("3.0.0",), indirect=True)
	242	def test_header_is_chainable(self, spec):
	243	header = {"schema": {"type": "string"}}
	244	spec.components.header("header1", header).header("header2", header)
	245	headers = get_headers(spec)
	246	assert "header1" in headers
	247	assert "header2" in headers
	248
	249	# Referenced headers are only supported in OAS 3.x
	250	@pytest.mark.parametrize("spec", ("3.0.0",), indirect=True)
	251	def test_header_duplicate_name(self, spec):
	252	spec.components.header("test_header", {"schema": {"type": "string"}})
	253	with pytest.raises(
	254	DuplicateComponentNameError,
	255	match='Another header with name "test_header" is already registered.',
	256	):
	257	spec.components.header("test_header", {"schema": {"type": "integer"}})
228	258
229	259	# Referenced examples are only supported in OAS 3.x
230	260	@pytest.mark.parametrize("spec", ("3.0.0",), indirect=True)

306	336	}
307	337	],
308	338	"responses": {
309		"200": {"schema": "Pet", "description": "successful operation"},
	339	"200": {"description": "successful operation"},
310	340	"400": {"description": "Invalid ID supplied"},
311	341	"404": {"description": "Pet not found"},
312	342	},

617	647	with pytest.raises(APISpecError, match=message):
618	648	spec.path("/pet/{petId}", operations={"dummy": {}})
619	649
	650	def test_path_resolve_response_schema(self, spec):
	651	schema = {"schema": "PetSchema"}
	652	if spec.openapi_version.major >= 3:
	653	schema = {"content": {"application/json": schema}}
	654	spec.path("/pet/{petId}", operations={"get": {"responses": {"200": schema}}})
	655	resp = get_paths(spec)["/pet/{petId}"]["get"]["responses"]["200"]
	656	if spec.openapi_version.major < 3:
	657	schema = resp["schema"]
	658	else:
	659	schema = resp["content"]["application/json"]["schema"]
	660	assert schema == build_ref(spec, "schema", "PetSchema")
	661
	662	# requestBody only exists in OAS 3
	663	@pytest.mark.parametrize("spec", ("3.0.0",), indirect=True)
	664	def test_path_resolve_request_body(self, spec):
	665	spec.path(
	666	"/pet/{petId}",
	667	operations={
	668	"get": {
	669	"requestBody": {
	670	"content": {"application/json": {"schema": "PetSchema"}}
	671	}
	672	}
	673	},
	674	)
	675	assert get_paths(spec)["/pet/{petId}"]["get"]["requestBody"]["content"][
	676	"application/json"
	677	]["schema"] == build_ref(spec, "schema", "PetSchema")
	678
	679	# "headers" components section only exists in OAS 3
	680	@pytest.mark.parametrize("spec", ("3.0.0",), indirect=True)
	681	def test_path_resolve_response_header(self, spec):
	682	response = {"headers": {"header_1": "Header_1"}}
	683	spec.path("/pet/{petId}", operations={"get": {"responses": {"200": response}}})
	684	resp = get_paths(spec)["/pet/{petId}"]["get"]["responses"]["200"]
	685	header_1 = resp["headers"]["header_1"]
	686	assert header_1 == build_ref(spec, "header", "Header_1")
	687
	688	# "examples" components section only exists in OAS 3
	689	@pytest.mark.parametrize("spec", ("3.0.0",), indirect=True)
	690	def test_path_resolve_response_examples(self, spec):
	691	response = {
	692	"content": {"application/json": {"examples": {"example_1": "Example_1"}}}
	693	}
	694	spec.path("/pet/{petId}", operations={"get": {"responses": {"200": response}}})
	695	resp = get_paths(spec)["/pet/{petId}"]["get"]["responses"]["200"]
	696	example_1 = resp["content"]["application/json"]["examples"]["example_1"]
	697	assert example_1 == build_ref(spec, "example", "Example_1")
	698
	699	# "examples" components section only exists in OAS 3
	700	@pytest.mark.parametrize("spec", ("3.0.0",), indirect=True)
	701	def test_path_resolve_request_body_examples(self, spec):
	702	request_body = {
	703	"content": {"application/json": {"examples": {"example_1": "Example_1"}}}
	704	}
	705	spec.path("/pet/{petId}", operations={"get": {"requestBody": request_body}})
	706	reqbdy = get_paths(spec)["/pet/{petId}"]["get"]["requestBody"]
	707	example_1 = reqbdy["content"]["application/json"]["examples"]["example_1"]
	708	assert example_1 == build_ref(spec, "example", "Example_1")
	709
	710	# "examples" components section only exists in OAS 3
	711	@pytest.mark.parametrize("spec", ("3.0.0",), indirect=True)
	712	def test_path_resolve_parameter_examples(self, spec):
	713	parameter = {
	714	"name": "test",
	715	"in": "query",
	716	"examples": {"example_1": "Example_1"},
	717	}
	718	spec.path("/pet/{petId}", operations={"get": {"parameters": [parameter]}})
	719	param = get_paths(spec)["/pet/{petId}"]["get"]["parameters"][0]
	720	example_1 = param["examples"]["example_1"]
	721	assert example_1 == build_ref(spec, "example", "Example_1")
	722
620	723
621	724	class TestPlugins:
622	725	@staticmethod

741	844	self.output = output
742	845
743	846	def path_helper(self, path, operations, **kwargs):
744		self.output.append("plugin_{}_path".format(self.index))
	847	self.output.append(f"plugin_{self.index}_path")
745	848
746	849	def operation_helper(self, path, operations, **kwargs):
747		self.output.append("plugin_{}_operations".format(self.index))
	850	self.output.append(f"plugin_{self.index}_operations")
748	851
749	852	def test_plugins_order(self):
750	853	"""Test plugins execution order in APISpec.path

+304

-18

tests/test_ext_marshmallow.py less more

1	1
2	2	import pytest
3	3
4		from marshmallow.fields import Field, DateTime, Dict, String, Nested, List
	4	from marshmallow.fields import Field, DateTime, Dict, String, Nested, List, TimeDelta
5	5	from marshmallow import Schema
6	6
7	7	from apispec import APISpec
8	8	from apispec.ext.marshmallow import MarshmallowPlugin
9		from apispec.ext.marshmallow.openapi import MARSHMALLOW_VERSION_INFO
10	9	from apispec.ext.marshmallow import common
11	10	from apispec.exceptions import APISpecError
12	11	from .schemas import (

232	231	reference = parameter["content"]["application/json"]["schema"]
233	232	assert reference == build_ref(spec, "schema", "Pet")
234	233
235		resolved_schema = spec.components._schemas["Pet"]
	234	resolved_schema = spec.components.schemas["Pet"]
236	235	assert resolved_schema["properties"]["name"]["type"] == "string"
237	236	assert resolved_schema["properties"]["password"]["type"] == "string"
238	237	assert resolved_schema["properties"]["id"]["type"] == "integer"

253	252	reference = response["content"]["application/json"]["schema"]
254	253	assert reference == build_ref(spec, "schema", "Pet")
255	254
256		resolved_schema = spec.components._schemas["Pet"]
	255	resolved_schema = spec.components.schemas["Pet"]
257	256	assert resolved_schema["properties"]["id"]["type"] == "integer"
258	257	assert resolved_schema["properties"]["name"]["type"] == "string"
259	258	assert resolved_schema["properties"]["password"]["type"] == "string"

266	265	reference = response["headers"]["PetHeader"]["schema"]
267	266	assert reference == build_ref(spec, "schema", "Pet")
268	267
269		resolved_schema = spec.components._schemas["Pet"]
	268	resolved_schema = spec.components.schemas["Pet"]
270	269	assert resolved_schema["properties"]["id"]["type"] == "integer"
271	270	assert resolved_schema["properties"]["name"]["type"] == "string"
272	271	assert resolved_schema["properties"]["password"]["type"] == "string"

327	326
328	327
329	328	class TestOperationHelper:
	329	@pytest.fixture
	330	def make_pet_callback_spec(self, spec_fixture):
	331	def _make_pet_spec(operations):
	332	spec_fixture.spec.path(
	333	path="/pet",
	334	operations={
	335	"post": {"callbacks": {"petEvent": {"petCallbackUrl": operations}}}
	336	},
	337	)
	338	return spec_fixture
	339
	340	return _make_pet_spec
	341
330	342	@pytest.mark.parametrize(
331	343	"pet_schema",
332	344	(PetSchema, PetSchema(), PetSchema(many=True), "tests.schemas.PetSchema"),

363	375	header_reference = get["responses"]["200"]["headers"]["PetHeader"]["schema"]
364	376	assert schema_reference == build_ref(spec_fixture.spec, "schema", "Pet")
365	377	assert header_reference == build_ref(spec_fixture.spec, "schema", "Pet")
366		assert len(spec_fixture.spec.components._schemas) == 1
367		resolved_schema = spec_fixture.spec.components._schemas["Pet"]
	378	assert len(spec_fixture.spec.components.schemas) == 1
	379	resolved_schema = spec_fixture.spec.components.schemas["Pet"]
368	380	assert resolved_schema == spec_fixture.openapi.schema2jsonschema(PetSchema)
369	381	assert get["responses"]["200"]["description"] == "successful operation"
370	382

412	424
413	425	assert schema_reference == build_ref(spec_fixture.spec, "schema", "Pet")
414	426	assert header_reference == build_ref(spec_fixture.spec, "schema", "Pet")
415		assert len(spec_fixture.spec.components._schemas) == 1
416		resolved_schema = spec_fixture.spec.components._schemas["Pet"]
	427	assert len(spec_fixture.spec.components.schemas) == 1
	428	resolved_schema = spec_fixture.spec.components.schemas["Pet"]
	429	assert resolved_schema == spec_fixture.openapi.schema2jsonschema(PetSchema)
	430	assert get["responses"]["200"]["description"] == "successful operation"
	431
	432	@pytest.mark.parametrize(
	433	"pet_schema",
	434	(PetSchema, PetSchema(), PetSchema(many=True), "tests.schemas.PetSchema"),
	435	)
	436	@pytest.mark.parametrize("spec_fixture", ("3.0.0",), indirect=True)
	437	def test_callback_schema_v3(self, make_pet_callback_spec, pet_schema):
	438	spec_fixture = make_pet_callback_spec(
	439	{
	440	"get": {
	441	"responses": {
	442	"200": {
	443	"content": {"application/json": {"schema": pet_schema}},
	444	"description": "successful operation",
	445	"headers": {"PetHeader": {"schema": pet_schema}},
	446	}
	447	}
	448	}
	449	}
	450	)
	451	p = get_paths(spec_fixture.spec)["/pet"]
	452	c = p["post"]["callbacks"]["petEvent"]["petCallbackUrl"]
	453	get = c["get"]
	454	if isinstance(pet_schema, Schema) and pet_schema.many is True:
	455	assert (
	456	get["responses"]["200"]["content"]["application/json"]["schema"]["type"]
	457	== "array"
	458	)
	459	schema_reference = get["responses"]["200"]["content"]["application/json"][
	460	"schema"
	461	]["items"]
	462	assert (
	463	get["responses"]["200"]["headers"]["PetHeader"]["schema"]["type"]
	464	== "array"
	465	)
	466	header_reference = get["responses"]["200"]["headers"]["PetHeader"][
	467	"schema"
	468	]["items"]
	469	else:
	470	schema_reference = get["responses"]["200"]["content"]["application/json"][
	471	"schema"
	472	]
	473	header_reference = get["responses"]["200"]["headers"]["PetHeader"]["schema"]
	474
	475	assert schema_reference == build_ref(spec_fixture.spec, "schema", "Pet")
	476	assert header_reference == build_ref(spec_fixture.spec, "schema", "Pet")
	477	assert len(spec_fixture.spec.components.schemas) == 1
	478	resolved_schema = spec_fixture.spec.components.schemas["Pet"]
417	479	assert resolved_schema == spec_fixture.openapi.schema2jsonschema(PetSchema)
418	480	assert get["responses"]["200"]["description"] == "successful operation"
419	481

439	501	p = get_paths(spec_fixture.spec)["/pet"]
440	502	get = p["get"]
441	503	assert get["parameters"] == spec_fixture.openapi.schema2parameters(
442		PetSchema(), default_in="query"
	504	PetSchema(), location="query"
443	505	)
444	506	post = p["post"]
445	507	assert post["parameters"] == spec_fixture.openapi.schema2parameters(
446	508	PetSchema,
447		default_in="body",
	509	location="body",
448	510	required=True,
449	511	name="pet",
450	512	description="a pet schema",

468	530	p = get_paths(spec_fixture.spec)["/pet"]
469	531	get = p["get"]
470	532	assert get["parameters"] == spec_fixture.openapi.schema2parameters(
471		PetSchema(), default_in="query"
	533	PetSchema(), location="query"
472	534	)
473	535	for parameter in get["parameters"]:
474	536	description = parameter.get("description", False)

485	547	assert post["requestBody"]["description"] == "a pet schema"
486	548	assert post["requestBody"]["required"]
487	549
	550	@pytest.mark.parametrize("spec_fixture", ("3.0.0",), indirect=True)
	551	def test_callback_schema_expand_parameters_v3(self, make_pet_callback_spec):
	552	spec_fixture = make_pet_callback_spec(
	553	{
	554	"get": {"parameters": [{"in": "query", "schema": PetSchema}]},
	555	"post": {
	556	"requestBody": {
	557	"description": "a pet schema",
	558	"required": True,
	559	"content": {"application/json": {"schema": PetSchema}},
	560	}
	561	},
	562	}
	563	)
	564	p = get_paths(spec_fixture.spec)["/pet"]
	565	c = p["post"]["callbacks"]["petEvent"]["petCallbackUrl"]
	566	get = c["get"]
	567	assert get["parameters"] == spec_fixture.openapi.schema2parameters(
	568	PetSchema(), location="query"
	569	)
	570	for parameter in get["parameters"]:
	571	description = parameter.get("description", False)
	572	assert description
	573	name = parameter["name"]
	574	assert description == PetSchema.description[name]
	575	post = c["post"]
	576	post_schema = spec_fixture.marshmallow_plugin.resolver.resolve_schema_dict(
	577	PetSchema
	578	)
	579	assert (
	580	post["requestBody"]["content"]["application/json"]["schema"] == post_schema
	581	)
	582	assert post["requestBody"]["description"] == "a pet schema"
	583	assert post["requestBody"]["required"]
	584
488	585	@pytest.mark.parametrize("spec_fixture", ("2.0",), indirect=True)
489	586	def test_schema_uses_ref_if_available_v2(self, spec_fixture):
490	587	spec_fixture.spec.components.schema("Pet", schema=PetSchema)

510	607	},
511	608	)
512	609	get = get_paths(spec_fixture.spec)["/pet"]["get"]
	610	assert get["responses"]["200"]["content"]["application/json"][
	611	"schema"
	612	] == build_ref(spec_fixture.spec, "schema", "Pet")
	613
	614	@pytest.mark.parametrize("spec_fixture", ("3.0.0",), indirect=True)
	615	def test_callback_schema_uses_ref_if_available_v3(self, make_pet_callback_spec):
	616	spec_fixture = make_pet_callback_spec(
	617	{
	618	"get": {
	619	"responses": {
	620	"200": {"content": {"application/json": {"schema": PetSchema}}}
	621	}
	622	}
	623	}
	624	)
	625	p = get_paths(spec_fixture.spec)["/pet"]
	626	c = p["post"]["callbacks"]["petEvent"]["petCallbackUrl"]
	627	get = c["get"]
513	628	assert get["responses"]["200"]["content"]["application/json"][
514	629	"schema"
515	630	] == build_ref(spec_fixture.spec, "schema", "Pet")

558	673	] == build_ref(spec, "schema", "Pet")
559	674
560	675	@pytest.mark.parametrize(
561		"pet_schema", (PetSchema, PetSchema(), "tests.schemas.PetSchema"),
	676	"pet_schema",
	677	(PetSchema, PetSchema(), "tests.schemas.PetSchema"),
562	678	)
563	679	def test_schema_name_resolver_returns_none_v2(self, pet_schema):
564	680	def resolver(schema):

578	694	assert "properties" in get["responses"]["200"]["schema"]
579	695
580	696	@pytest.mark.parametrize(
581		"pet_schema", (PetSchema, PetSchema(), "tests.schemas.PetSchema"),
	697	"pet_schema",
	698	(PetSchema, PetSchema(), "tests.schemas.PetSchema"),
582	699	)
583	700	def test_schema_name_resolver_returns_none_v3(self, pet_schema):
584	701	def resolver(schema):

605	722	"properties"
606	723	in get["responses"]["200"]["content"]["application/json"]["schema"]
607	724	)
	725
	726	def test_callback_schema_uses_ref_if_available_name_resolver_returns_none_v3(self):
	727	def resolver(schema):
	728	return None
	729
	730	spec = APISpec(
	731	title="Test auto-reference",
	732	version="0.1",
	733	openapi_version="3.0.0",
	734	plugins=(MarshmallowPlugin(schema_name_resolver=resolver),),
	735	)
	736	spec.components.schema("Pet", schema=PetSchema)
	737	spec.path(
	738	path="/pet",
	739	operations={
	740	"post": {
	741	"callbacks": {
	742	"petEvent": {
	743	"petCallbackUrl": {
	744	"get": {
	745	"responses": {
	746	"200": {
	747	"content": {
	748	"application/json": {
	749	"schema": PetSchema
	750	}
	751	}
	752	}
	753	}
	754	}
	755	}
	756	}
	757	}
	758	}
	759	},
	760	)
	761	p = get_paths(spec)["/pet"]
	762	c = p["post"]["callbacks"]["petEvent"]["petCallbackUrl"]
	763	get = c["get"]
	764	assert get["responses"]["200"]["content"]["application/json"][
	765	"schema"
	766	] == build_ref(spec, "schema", "Pet")
608	767
609	768	@pytest.mark.parametrize("spec_fixture", ("2.0",), indirect=True)
610	769	def test_schema_uses_ref_in_parameters_and_request_body_if_available_v2(

645	804	p = get_paths(spec_fixture.spec)["/pet"]
646	805	assert "schema" in p["get"]["parameters"][0]
647	806	post = p["post"]
	807	schema_ref = post["requestBody"]["content"]["application/json"]["schema"]
	808	assert schema_ref == build_ref(spec_fixture.spec, "schema", "Pet")
	809
	810	@pytest.mark.parametrize("spec_fixture", ("3.0.0",), indirect=True)
	811	def test_callback_schema_uses_ref_in_parameters_and_request_body_if_available_v3(
	812	self, make_pet_callback_spec
	813	):
	814	spec_fixture = make_pet_callback_spec(
	815	{
	816	"get": {"parameters": [{"in": "query", "schema": PetSchema}]},
	817	"post": {
	818	"requestBody": {
	819	"content": {"application/json": {"schema": PetSchema}}
	820	}
	821	},
	822	}
	823	)
	824	p = get_paths(spec_fixture.spec)["/pet"]
	825	c = p["post"]["callbacks"]["petEvent"]["petCallbackUrl"]
	826	assert "schema" in c["get"]["parameters"][0]
	827	post = c["post"]
648	828	schema_ref = post["requestBody"]["content"]["application/json"]["schema"]
649	829	assert schema_ref == build_ref(spec_fixture.spec, "schema", "Pet")
650	830

708	888	},
709	889	)
710	890	get = get_paths(spec_fixture.spec)["/pet"]["get"]
	891	assert len(get["parameters"]) == 1
	892	resolved_schema = {
	893	"type": "array",
	894	"items": build_ref(spec_fixture.spec, "schema", "Pet"),
	895	}
	896	request_schema = get["parameters"][0]["content"]["application/json"]["schema"]
	897	assert request_schema == resolved_schema
	898	response_schema = get["responses"]["200"]["content"]["application/json"][
	899	"schema"
	900	]
	901	assert response_schema == resolved_schema
	902
	903	@pytest.mark.parametrize("spec_fixture", ("3.0.0",), indirect=True)
	904	def test_callback_schema_array_uses_ref_if_available_v3(
	905	self, make_pet_callback_spec
	906	):
	907	spec_fixture = make_pet_callback_spec(
	908	{
	909	"get": {
	910	"parameters": [
	911	{
	912	"name": "Pet",
	913	"in": "query",
	914	"content": {
	915	"application/json": {
	916	"schema": {"type": "array", "items": PetSchema}
	917	}
	918	},
	919	}
	920	],
	921	"responses": {
	922	"200": {
	923	"content": {
	924	"application/json": {
	925	"schema": {"type": "array", "items": PetSchema}
	926	}
	927	}
	928	}
	929	},
	930	}
	931	}
	932	)
	933	p = get_paths(spec_fixture.spec)["/pet"]
	934	c = p["post"]["callbacks"]["petEvent"]["petCallbackUrl"]
	935	get = c["get"]
711	936	assert len(get["parameters"]) == 1
712	937	resolved_schema = {
713	938	"type": "array",

784	1009	},
785	1010	}
786	1011
	1012	@pytest.mark.parametrize("spec_fixture", ("3.0.0",), indirect=True)
	1013	def test_callback_schema_partially_v3(self, make_pet_callback_spec):
	1014	spec_fixture = make_pet_callback_spec(
	1015	{
	1016	"get": {
	1017	"responses": {
	1018	"200": {
	1019	"content": {
	1020	"application/json": {
	1021	"schema": {
	1022	"type": "object",
	1023	"properties": {
	1024	"mother": PetSchema,
	1025	"father": PetSchema,
	1026	},
	1027	}
	1028	}
	1029	}
	1030	}
	1031	}
	1032	}
	1033	}
	1034	)
	1035	p = get_paths(spec_fixture.spec)["/pet"]
	1036	c = p["post"]["callbacks"]["petEvent"]["petCallbackUrl"]
	1037	get = c["get"]
	1038	assert get["responses"]["200"]["content"]["application/json"]["schema"] == {
	1039	"type": "object",
	1040	"properties": {
	1041	"mother": build_ref(spec_fixture.spec, "schema", "Pet"),
	1042	"father": build_ref(spec_fixture.spec, "schema", "Pet"),
	1043	},
	1044	}
	1045
787	1046	def test_parameter_reference(self, spec_fixture):
788	1047	if spec_fixture.spec.openapi_version.major < 3:
789	1048	param = {"schema": PetSchema}

818	1077
819	1078	def test_schema_global_state_untouched_2parameters(self, spec_fixture):
820	1079	assert get_nested_schema(RunSchema, "sample") is None
821		data = spec_fixture.openapi.schema2parameters(RunSchema)
	1080	data = spec_fixture.openapi.schema2parameters(RunSchema, location="json")
822	1081	json.dumps(data)
823	1082	assert get_nested_schema(RunSchema, "sample") is None
	1083
	1084	def test_resolve_schema_dict_ref_as_string(self, spec):
	1085	schema = {"schema": "PetSchema"}
	1086	if spec.openapi_version.major >= 3:
	1087	schema = {"content": {"application/json": schema}}
	1088	spec.path("/pet/{petId}", operations={"get": {"responses": {"200": schema}}})
	1089	resp = get_paths(spec)["/pet/{petId}"]["get"]["responses"]["200"]
	1090	if spec.openapi_version.major < 3:
	1091	schema = resp["schema"]
	1092	else:
	1093	schema = resp["content"]["application/json"]["schema"]
	1094	assert schema == build_ref(spec, "schema", "PetSchema")
824	1095
825	1096
826	1097	class TestCircularReference:

882	1153	assert "default" not in props["numbers"]
883	1154
884	1155
885		@pytest.mark.skipif(
886		MARSHMALLOW_VERSION_INFO[0] < 3, reason="Values ignored in marshmallow 2"
887		)
888	1156	class TestDictValues:
889	1157	def test_dict_values_resolve_to_additional_properties(self, spec):
890	1158	class SchemaWithDict(Schema):

928	1196
929	1197	result = get_schemas(spec)["SchemaWithList"]["properties"]["list_field"]
930	1198	assert result == {"items": build_ref(spec, "schema", "Pet"), "type": "array"}
	1199
	1200
	1201	class TestTimeDelta:
	1202	def test_timedelta_x_unit(self, spec):
	1203	class SchemaWithTimeDelta(Schema):
	1204	sec = TimeDelta("seconds")
	1205	day = TimeDelta("days")
	1206
	1207	spec.components.schema("SchemaWithTimeDelta", schema=SchemaWithTimeDelta)
	1208
	1209	assert (
	1210	get_schemas(spec)["SchemaWithTimeDelta"]["properties"]["sec"]["x-unit"]
	1211	== "seconds"
	1212	)
	1213	assert (
	1214	get_schemas(spec)["SchemaWithTimeDelta"]["properties"]["day"]["x-unit"]
	1215	== "days"
	1216	)

-0

tests/test_ext_marshmallow_common.py less more

78	78	assert list(get_fields(ExcludeSchema, exclude_dump_only=True).keys()) == [
79	79	"field5"
80	80	]
	81
	82	# regression test for https://github.com/marshmallow-code/apispec/issues/673
	83	def test_schema_with_field_named_fields(self):
	84	class TestSchema(Schema):
	85	fields = fields.Int()
	86
	87	schema_fields = get_fields(TestSchema)
	88	assert list(schema_fields.keys()) == ["fields"]
	89	assert isinstance(schema_fields["fields"], fields.Int)

+138

-21

tests/test_ext_marshmallow_field.py less more

3	3	import pytest
4	4	from marshmallow import fields, validate
5	5
6		from apispec.ext.marshmallow.openapi import MARSHMALLOW_VERSION_INFO
7
8	6	from .schemas import CategorySchema, CustomList, CustomStringField, CustomIntegerField
9		from .utils import build_ref
	7	from .utils import build_ref, get_schemas
10	8
11	9
12	10	def test_field2choices_preserving_order(openapi):

29	27	(fields.DateTime, "string"),
30	28	(fields.Date, "string"),
31	29	(fields.Time, "string"),
	30	(fields.TimeDelta, "integer"),
32	31	(fields.Email, "string"),
33	32	(fields.URL, "string"),
34	33	# Custom fields inherit types from their parents

60	59	@pytest.mark.parametrize(
61	60	("FieldClass", "expected_format"),
62	61	[
63		(fields.Integer, "int32"),
64		(fields.Float, "float"),
65	62	(fields.UUID, "uuid"),
66	63	(fields.DateTime, "date-time"),
67	64	(fields.Date, "date"),

76	73
77	74
78	75	def test_field_with_description(spec_fixture):
79		field = fields.Str(description="a username")
	76	field = fields.Str(metadata={"description": "a username"})
80	77	res = spec_fixture.openapi.field2property(field)
81	78	assert res["description"] == "a username"
82	79

94	91
95	92
96	93	def test_datetime_field_with_missing(spec_fixture):
97		if MARSHMALLOW_VERSION_INFO[0] < 3:
98		field = fields.Date(missing=dt.date(2014, 7, 18).isoformat())
99		else:
100		field = fields.Date(missing=dt.date(2014, 7, 18))
	94	field = fields.Date(missing=dt.date(2014, 7, 18))
101	95	res = spec_fixture.openapi.field2property(field)
102	96	assert res["default"] == dt.date(2014, 7, 18).isoformat()
103	97

109	103
110	104
111	105	def test_field_with_doc_default(spec_fixture):
112		field = fields.Str(doc_default="Manual default")
	106	field = fields.Str(metadata={"doc_default": "Manual default"})
113	107	res = spec_fixture.openapi.field2property(field)
114	108	assert res["default"] == "Manual default"
115	109
116	110
117	111	def test_field_with_doc_default_and_missing(spec_fixture):
118		field = fields.Int(doc_default=42, missing=12)
	112	field = fields.Int(missing=12, metadata={"doc_default": 42})
119	113	res = spec_fixture.openapi.field2property(field)
120	114	assert res["default"] == 42
121	115

135	129	def test_only_allows_valid_properties_in_metadata(spec_fixture):
136	130	field = fields.Str(
137	131	missing="foo",
138		description="foo",
139		enum=["red", "blue"],
140		allOf=["bar"],
141		not_valid="lol",
	132	metadata={
	133	"description": "foo",
	134	"not_valid": "lol",
	135	"allOf": ["bar"],
	136	"enum": ["red", "blue"],
	137	},
142	138	)
143	139	res = spec_fixture.openapi.field2property(field)
144	140	assert res["default"] == field.missing

160	156
161	157
162	158	def test_field_with_additional_metadata(spec_fixture):
163		field = fields.Str(minLength=6, maxLength=100)
	159	field = fields.Str(metadata={"minLength": 6, "maxLength": 100})
164	160	res = spec_fixture.openapi.field2property(field)
165	161	assert res["maxLength"] == 100
166	162	assert res["minLength"] == 6
167	163
168	164
	165	@pytest.mark.parametrize("spec_fixture", ("2.0", "3.0.0", "3.1.0"), indirect=True)
169	166	def test_field_with_allow_none(spec_fixture):
170	167	field = fields.Str(allow_none=True)
171	168	res = spec_fixture.openapi.field2property(field)
172	169	if spec_fixture.openapi.openapi_version.major < 3:
173	170	assert res["x-nullable"] is True
	171	elif spec_fixture.openapi.openapi_version.minor < 1:
	172	assert res["nullable"] is True
174	173	else:
175		assert res["nullable"] is True
	174	assert "nullable" not in res
	175	assert res["type"] == ["string", "null"]
	176
	177
	178	def test_field_with_dump_only(spec_fixture):
	179	field = fields.Str(dump_only=True)
	180	res = spec_fixture.openapi.field2property(field)
	181	assert res["readOnly"] is True
	182
	183
	184	@pytest.mark.parametrize("spec_fixture", ("2.0", "3.0.0", "3.1.0"), indirect=True)
	185	def test_field_with_load_only(spec_fixture):
	186	field = fields.Str(load_only=True)
	187	res = spec_fixture.openapi.field2property(field)
	188	if spec_fixture.openapi.openapi_version.major < 3:
	189	assert "writeOnly" not in res
	190	else:
	191	assert res["writeOnly"] is True
	192
	193
	194	def test_field_with_range_no_type(spec_fixture):
	195	field = fields.Field(validate=validate.Range(min=1, max=10))
	196	res = spec_fixture.openapi.field2property(field)
	197	assert res["x-minimum"] == 1
	198	assert res["x-maximum"] == 10
	199	assert "type" not in res
	200
	201
	202	@pytest.mark.parametrize("field", (fields.Number, fields.Integer))
	203	def test_field_with_range_string_type(spec_fixture, field):
	204	field = field(validate=validate.Range(min=1, max=10))
	205	res = spec_fixture.openapi.field2property(field)
	206	assert res["minimum"] == 1
	207	assert res["maximum"] == 10
	208	assert isinstance(res["type"], str)
	209
	210
	211	@pytest.mark.parametrize("spec_fixture", ("3.1.0",), indirect=True)
	212	def test_field_with_range_type_list_with_number(spec_fixture):
	213	@spec_fixture.openapi.map_to_openapi_type(["integer", "null"], None)
	214	class NullableInteger(fields.Field):
	215	"""Nullable integer"""
	216
	217	field = NullableInteger(validate=validate.Range(min=1, max=10))
	218	res = spec_fixture.openapi.field2property(field)
	219	assert res["minimum"] == 1
	220	assert res["maximum"] == 10
	221	assert res["type"] == ["integer", "null"]
	222
	223
	224	@pytest.mark.parametrize("spec_fixture", ("3.1.0",), indirect=True)
	225	def test_field_with_range_type_list_without_number(spec_fixture):
	226	@spec_fixture.openapi.map_to_openapi_type(["string", "null"], None)
	227	class NullableInteger(fields.Field):
	228	"""Nullable integer"""
	229
	230	field = NullableInteger(validate=validate.Range(min=1, max=10))
	231	res = spec_fixture.openapi.field2property(field)
	232	assert res["x-minimum"] == 1
	233	assert res["x-maximum"] == 10
	234	assert res["type"] == ["string", "null"]
176	235
177	236
178	237	def test_field_with_str_regex(spec_fixture):

207	266	spec_fixture.spec.components.schema("Category", schema=CategorySchema)
208	267	category = fields.Nested(
209	268	CategorySchema,
210		description="A category",
211		invalid_property="not in the result",
212		x_extension="A great extension",
	269	metadata={
	270	"description": "A category",
	271	"invalid_property": "not in the result",
	272	"x_extension": "A great extension",
	273	},
213	274	)
214	275	result = spec_fixture.openapi.field2property(category)
215	276	assert result == {

273	334	}
274	335
275	336
	337	class TestField2PropertyPluck:
	338	@pytest.fixture(autouse=True)
	339	def _setup(self, spec_fixture):
	340	self.field2property = spec_fixture.openapi.field2property
	341
	342	self.spec = spec_fixture.spec
	343	self.spec.components.schema("Category", schema=CategorySchema)
	344	self.unplucked = get_schemas(self.spec)["Category"]["properties"]["breed"]
	345
	346	def test_spec(self, spec_fixture):
	347	breed = fields.Pluck(CategorySchema, "breed")
	348	assert self.field2property(breed) == self.unplucked
	349
	350	def test_with_property(self):
	351	breed = fields.Pluck(CategorySchema, "breed", dump_only=True)
	352	assert self.field2property(breed) == {**self.unplucked, "readOnly": True}
	353
	354	def test_metadata(self):
	355	breed = fields.Pluck(
	356	CategorySchema,
	357	"breed",
	358	metadata={
	359	"description": "Category breed",
	360	"invalid_property": "not in the result",
	361	"x_extension": "A great extension",
	362	},
	363	)
	364	assert self.field2property(breed) == {
	365	**self.unplucked,
	366	"description": "Category breed",
	367	"x-extension": "A great extension",
	368	}
	369
	370	def test_many(self):
	371	breed = fields.Pluck(CategorySchema, "breed", many=True)
	372	assert self.field2property(breed) == {"type": "array", "items": self.unplucked}
	373
	374	def test_many_with_property(self):
	375	breed = fields.Pluck(CategorySchema, "breed", many=True, dump_only=True)
	376	assert self.field2property(breed) == {
	377	"items": self.unplucked,
	378	"type": "array",
	379	"readOnly": True,
	380	}
	381
	382
276	383	def test_custom_properties_for_custom_fields(spec_fixture):
277	384	def custom_string2properties(self, field, **kwargs):
278	385	ret = {}

292	399	assert properties["x-customString"] == (
293	400	spec_fixture.openapi.openapi_version == "2.0"
294	401	)
	402
	403
	404	def test_field2property_with_non_string_metadata_keys(spec_fixture):
	405	class _DesertSentinel:
	406	pass
	407
	408	field = fields.Boolean(metadata={"description": "A description"})
	409	field.metadata[_DesertSentinel()] = "to be ignored"
	410	result = spec_fixture.openapi.field2property(field)
	411	assert result == {"description": "A description", "type": "boolean"}

+132

-130

tests/test_ext_marshmallow_openapi.py less more

0	0	import pytest
1
2		from marshmallow import fields, Schema, validate
	1	from datetime import datetime
	2
	3	from marshmallow import EXCLUDE, fields, INCLUDE, RAISE, Schema, validate
3	4
4	5	from apispec.ext.marshmallow import MarshmallowPlugin
5		from apispec.ext.marshmallow.openapi import MARSHMALLOW_VERSION_INFO
6	6	from apispec import exceptions, utils, APISpec
7	7
8	8	from .schemas import CustomList, CustomStringField

11	11
12	12	class TestMarshmallowFieldToOpenAPI:
13	13	def test_fields_with_missing_load(self, openapi):
14		field_dict = {"field": fields.Str(default="foo", missing="bar")}
15		res = openapi.fields2parameters(field_dict, default_in="query")
	14	class MySchema(Schema):
	15	field = fields.Str(default="foo", missing="bar")
	16
	17	res = openapi.schema2parameters(MySchema, location="query")
16	18	if openapi.openapi_version.major < 3:
17	19	assert res[0]["default"] == "bar"
18	20	else:
19	21	assert res[0]["schema"]["default"] == "bar"
20
21		def test_fields_with_location(self, openapi):
22		field_dict = {"field": fields.Str(location="querystring")}
23		res = openapi.fields2parameters(field_dict, default_in="headers")
24		assert res[0]["in"] == "query"
25
26		# json/body is invalid for OpenAPI 3
27		@pytest.mark.parametrize("openapi", ("2.0",), indirect=True)
28		def test_fields_with_multiple_json_locations(self, openapi):
29		field_dict = {
30		"field1": fields.Str(location="json", required=True),
31		"field2": fields.Str(location="json", required=True),
32		"field3": fields.Str(location="json"),
33		}
34		res = openapi.fields2parameters(field_dict, default_in=None)
35		assert len(res) == 1
36		assert res[0]["in"] == "body"
37		assert res[0]["required"] is False
38		assert "field1" in res[0]["schema"]["properties"]
39		assert "field2" in res[0]["schema"]["properties"]
40		assert "field3" in res[0]["schema"]["properties"]
41		assert "required" in res[0]["schema"]
42		assert len(res[0]["schema"]["required"]) == 2
43		assert "field1" in res[0]["schema"]["required"]
44		assert "field2" in res[0]["schema"]["required"]
45
46		def test_fields2parameters_does_not_modify_metadata(self, openapi):
47		field_dict = {"field": fields.Str(location="querystring")}
48		res = openapi.fields2parameters(field_dict, default_in="headers")
49		assert res[0]["in"] == "query"
50
51		res = openapi.fields2parameters(field_dict, default_in="headers")
52		assert res[0]["in"] == "query"
53
54		def test_fields_location_mapping(self, openapi):
55		field_dict = {"field": fields.Str(location="cookies")}
56		res = openapi.fields2parameters(field_dict, default_in="headers")
57		assert res[0]["in"] == "cookie"
58
59		def test_fields_default_location_mapping(self, openapi):
60		field_dict = {"field": fields.Str()}
61		res = openapi.fields2parameters(field_dict, default_in="headers")
62		assert res[0]["in"] == "header"
63	22
64	23	# json/body is invalid for OpenAPI 3
65	24	@pytest.mark.parametrize("openapi", ("2.0",), indirect=True)

68	27	id = fields.Int()
69	28
70	29	schema = ExampleSchema(many=True)
71		res = openapi.schema2parameters(schema=schema, default_in="json")
	30	res = openapi.schema2parameters(schema=schema, location="json")
72	31	assert res[0]["in"] == "body"
73	32
74	33	def test_fields_with_dump_only(self, openapi):
75	34	class UserSchema(Schema):
76	35	name = fields.Str(dump_only=True)
77	36
78		res = openapi.fields2parameters(UserSchema._declared_fields, default_in="query")
	37	res = openapi.schema2parameters(schema=UserSchema(), location="query")
79	38	assert len(res) == 0
80		res = openapi.fields2parameters(UserSchema().fields, default_in="query")
	39
	40	class UserSchema(Schema):
	41	name = fields.Str()
	42
	43	class Meta:
	44	dump_only = ("name",)
	45
	46	res = openapi.schema2parameters(schema=UserSchema(), location="query")
81	47	assert len(res) == 0
82	48
83		class UserSchema(Schema):
84		name = fields.Str()
85
86		class Meta:
87		dump_only = ("name",)
88
89		res = openapi.schema2parameters(schema=UserSchema, default_in="query")
90		assert len(res) == 0
91
92	49
93	50	class TestMarshmallowSchemaToModelDefinition:
94		def test_invalid_schema(self, openapi):
95		with pytest.raises(ValueError):
96		openapi.schema2jsonschema(None)
97
98	51	def test_schema2jsonschema_with_explicit_fields(self, openapi):
99	52	class UserSchema(Schema):
100	53	_id = fields.Int()
101		email = fields.Email(description="email address of the user")
	54	email = fields.Email(metadata={"description": "email address of the user"})
102	55	name = fields.Str()
103	56
104	57	class Meta:

113	66	assert props["email"]["format"] == "email"
114	67	assert props["email"]["description"] == "email address of the user"
115	68
116		@pytest.mark.skipif(
117		MARSHMALLOW_VERSION_INFO[0] >= 3, reason="Behaviour changed in marshmallow 3"
118		)
119		def test_schema2jsonschema_override_name_ma2(self, openapi):
120		class ExampleSchema(Schema):
121		_id = fields.Int(load_from="id", dump_to="id")
122		_dt = fields.Int(load_from="lf_no_match", dump_to="dt")
123		_lf = fields.Int(load_from="lf")
124		_global = fields.Int(load_from="global", dump_to="global")
125
126		class Meta:
127		exclude = ("_global",)
128
129		res = openapi.schema2jsonschema(ExampleSchema)
130		assert res["type"] == "object"
131		props = res["properties"]
132		# `_id` renamed to `id`
133		assert "_id" not in props and props["id"]["type"] == "integer"
134		# `load_from` and `dump_to` do not match, `dump_to` is used
135		assert "lf_no_match" not in props
136		assert props["dt"]["type"] == "integer"
137		# `load_from` and no `dump_to`, `load_from` is used
138		assert props["lf"]["type"] == "integer"
139		# `_global` excluded correctly
140		assert "_global" not in props and "global" not in props
141
142		@pytest.mark.skipif(
143		MARSHMALLOW_VERSION_INFO[0] < 3, reason="Behaviour changed in marshmallow 3"
144		)
145		def test_schema2jsonschema_override_name_ma3(self, openapi):
	69	def test_schema2jsonschema_override_name(self, openapi):
146	70	class ExampleSchema(Schema):
147	71	_id = fields.Int(data_key="id")
148	72	_global = fields.Int(data_key="global")

206	130
207	131	res = openapi.schema2jsonschema(WhiteStripesSchema)
208	132	assert set(res["properties"].keys()) == {"guitarist", "drummer"}
	133
	134	def test_unknown_values_disallow(self, openapi):
	135	class UnknownRaiseSchema(Schema):
	136	class Meta:
	137	unknown = RAISE
	138
	139	first = fields.Str()
	140
	141	res = openapi.schema2jsonschema(UnknownRaiseSchema)
	142	assert res["additionalProperties"] is False
	143
	144	def test_unknown_values_allow(self, openapi):
	145	class UnknownIncludeSchema(Schema):
	146	class Meta:
	147	unknown = INCLUDE
	148
	149	first = fields.Str()
	150
	151	res = openapi.schema2jsonschema(UnknownIncludeSchema)
	152	assert res["additionalProperties"] is True
	153
	154	def test_unknown_values_ignore(self, openapi):
	155	class UnknownExcludeSchema(Schema):
	156	class Meta:
	157	unknown = EXCLUDE
	158
	159	first = fields.Str()
	160
	161	res = openapi.schema2jsonschema(UnknownExcludeSchema)
	162	assert "additionalProperties" not in res
209	163
210	164	def test_only_explicitly_declared_fields_are_translated(self, openapi):
211	165	class UserSchema(Schema):

226	180	assert "email" not in props
227	181
228	182	def test_observed_field_name_for_required_field(self, openapi):
229		if MARSHMALLOW_VERSION_INFO[0] < 3:
230		fields_dict = {
231		"user_id": fields.Int(load_from="id", dump_to="id", required=True)
232		}
233		else:
234		fields_dict = {"user_id": fields.Int(data_key="id", required=True)}
235
	183	fields_dict = {"user_id": fields.Int(data_key="id", required=True)}
236	184	res = openapi.fields2jsonschema(fields_dict)
237	185	assert res["required"] == ["id"]
238	186

250	198	class NotASchema:
251	199	pass
252	200
253		expected_error = "{!r} doesn't have either `fields` or `_declared_fields`.".format(
254		NotASchema
	201	expected_error = (
	202	f"{NotASchema!r} is neither a Schema class nor a Schema instance."
255	203	)
256	204	with pytest.raises(ValueError, match=expected_error):
257	205	openapi.schema2jsonschema(NotASchema)

260	208	class TestMarshmallowSchemaToParameters:
261	209	@pytest.mark.parametrize("ListClass", [fields.List, CustomList])
262	210	def test_field_multiple(self, ListClass, openapi):
263		field = ListClass(fields.Str, location="querystring")
264		res = openapi.field2parameter(field, name="field", default_in=None)
	211	field = ListClass(fields.Str)
	212	res = openapi._field2parameter(field, name="field", location="query")
265	213	assert res["in"] == "query"
266	214	if openapi.openapi_version.major < 3:
267	215	assert res["type"] == "array"

274	222	assert res["explode"] is True
275	223
276	224	def test_field_required(self, openapi):
277		field = fields.Str(required=True, location="query")
278		res = openapi.field2parameter(field, name="field", default_in=None)
	225	field = fields.Str(required=True)
	226	res = openapi._field2parameter(field, name="field", location="query")
279	227	assert res["required"] is True
280	228
281		def test_invalid_schema(self, openapi):
282		with pytest.raises(ValueError):
283		openapi.schema2parameters(None)
	229	def test_schema_partial(self, openapi):
	230	class UserSchema(Schema):
	231	field = fields.Str(required=True)
	232
	233	res_nodump = openapi.schema2parameters(
	234	UserSchema(partial=True), location="query"
	235	)
	236
	237	param = res_nodump[0]
	238	assert param["required"] is False
	239
	240	def test_schema_partial_list(self, openapi):
	241	class UserSchema(Schema):
	242	field = fields.Str(required=True)
	243	partial_field = fields.Str(required=True)
	244
	245	res_nodump = openapi.schema2parameters(
	246	UserSchema(partial=("partial_field",)), location="query"
	247	)
	248
	249	param = next(p for p in res_nodump if p["name"] == "field")
	250	assert param["required"] is True
	251	param = next(p for p in res_nodump if p["name"] == "partial_field")
	252	assert param["required"] is False
284	253
285	254	# json/body is invalid for OpenAPI 3
286	255	@pytest.mark.parametrize("openapi", ("2.0",), indirect=True)

289	258	name = fields.Str()
290	259	email = fields.Email()
291	260
292		res = openapi.schema2parameters(UserSchema, default_in="body")
	261	res = openapi.schema2parameters(UserSchema, location="body")
293	262	assert len(res) == 1
294	263	param = res[0]
295	264	assert param["in"] == "body"

302	271	name = fields.Str()
303	272	email = fields.Email(dump_only=True)
304	273
305		res_nodump = openapi.schema2parameters(UserSchema, default_in="body")
	274	res_nodump = openapi.schema2parameters(UserSchema, location="body")
306	275	assert len(res_nodump) == 1
307	276	param = res_nodump[0]
308	277	assert param["in"] == "body"

315	284	name = fields.Str()
316	285	email = fields.Email()
317	286
318		res = openapi.schema2parameters(UserSchema(many=True), default_in="body")
	287	res = openapi.schema2parameters(UserSchema(many=True), location="body")
319	288	assert len(res) == 1
320	289	param = res[0]
321	290	assert param["in"] == "body"

327	296	name = fields.Str()
328	297	email = fields.Email()
329	298
330		res = openapi.schema2parameters(UserSchema, default_in="query")
	299	res = openapi.schema2parameters(UserSchema, location="query")
331	300	assert len(res) == 2
332	301	res.sort(key=lambda param: param["name"])
333	302	assert res[0]["name"] == "email"

340	309	name = fields.Str()
341	310	email = fields.Email()
342	311
343		res = openapi.schema2parameters(UserSchema(), default_in="query")
	312	res = openapi.schema2parameters(UserSchema(), location="query")
344	313	assert len(res) == 2
345	314	res.sort(key=lambda param: param["name"])
346	315	assert res[0]["name"] == "email"

354	323	email = fields.Email()
355	324
356	325	with pytest.raises(AssertionError):
357		openapi.schema2parameters(UserSchema(many=True), default_in="query")
	326	openapi.schema2parameters(UserSchema(many=True), location="query")
358	327
359	328	def test_fields_query(self, openapi):
360		field_dict = {"name": fields.Str(), "email": fields.Email()}
361		res = openapi.fields2parameters(field_dict, default_in="query")
	329	class MySchema(Schema):
	330	name = fields.Str()
	331	email = fields.Email()
	332
	333	res = openapi.schema2parameters(MySchema, location="query")
362	334	assert len(res) == 2
363	335	res.sort(key=lambda param: param["name"])
364	336	assert res[0]["name"] == "email"

370	342	class NotASchema:
371	343	pass
372	344
373		expected_error = "{!r} doesn't have either `fields` or `_declared_fields`".format(
374		NotASchema
	345	expected_error = (
	346	f"{NotASchema!r} is neither a Schema class nor a Schema instance."
375	347	)
376	348	with pytest.raises(ValueError, match=expected_error):
377	349	openapi.schema2jsonschema(NotASchema)

418	390	assert ("i" in props) == (modifier == "only")
419	391	assert ("j" not in props) == (modifier == "only")
420	392
	393	def test_schema2jsonschema_with_plucked_field(self, spec_fixture):
	394	class PetSchema(Schema):
	395	breed = fields.Pluck(CategorySchema, "breed")
	396
	397	category_schema = spec_fixture.openapi.schema2jsonschema(CategorySchema)
	398	pet_schema = spec_fixture.openapi.schema2jsonschema(PetSchema)
	399	assert (
	400	pet_schema["properties"]["breed"] == category_schema["properties"]["breed"]
	401	)
	402
421	403	def test_schema2jsonschema_with_nested_fields_with_adhoc_changes(
422	404	self, spec_fixture
423	405	):

440	422	assert props["Category"] == spec_fixture.openapi.schema2jsonschema(
441	423	CategorySchema
442	424	)
	425
	426	def test_schema2jsonschema_with_plucked_fields_with_adhoc_changes(
	427	self, spec_fixture
	428	):
	429	category_schema = CategorySchema()
	430	category_schema.fields["breed"].dump_only = True
	431
	432	class PetSchema(Schema):
	433	breed = fields.Pluck(category_schema, "breed", many=True)
	434
	435	spec_fixture.spec.components.schema("Pet", schema=PetSchema)
	436	props = get_schemas(spec_fixture.spec)["Pet"]["properties"]
	437
	438	assert props["breed"]["items"]["readOnly"] is True
443	439
444	440	def test_schema2jsonschema_with_nested_excluded_fields(self, spec):
445	441	category_schema = CategorySchema(exclude=("breed",))

476	472	"required": True,
477	473	"type": "string",
478	474	},
479		openapi.field2parameter(
	475	openapi._field2parameter(
480	476	field=fields.List(
481	477	fields.Str(),
482	478	validate=validate.OneOf(["freddie", "roger"]),
483		location="querystring",
484	479	),
485		default_in=None,
	480	location="query",
486	481	name="body",
487	482	),
488	483	]
489		+ openapi.schema2parameters(PageSchema, default_in="query"),
	484	+ openapi.schema2parameters(PageSchema, location="query"),
490	485	"responses": {200: {"schema": PetSchema, "description": "A pet"}},
491	486	},
492	487	"post": {

499	494	"type": "string",
500	495	}
501	496	]
502		+ openapi.schema2parameters(CategorySchema, default_in="body")
	497	+ openapi.schema2parameters(CategorySchema, location="body")
503	498	),
504	499	"responses": {201: {"schema": PetSchema, "description": "A pet"}},
505	500	},

534	529	"required": True,
535	530	"schema": {"type": "string"},
536	531	},
537		openapi.field2parameter(
	532	openapi._field2parameter(
538	533	field=fields.List(
539	534	fields.Str(),
540	535	validate=validate.OneOf(["freddie", "roger"]),
541		location="querystring",
542	536	),
543		default_in=None,
	537	location="query",
544	538	name="body",
545	539	),
546	540	]
547		+ openapi.schema2parameters(PageSchema, default_in="query"),
	541	+ openapi.schema2parameters(PageSchema, location="query"),
548	542	"responses": {
549	543	200: {
550	544	"description": "success",

585	579	class ValidationSchema(Schema):
586	580	id = fields.Int(dump_only=True)
587	581	range = fields.Int(validate=validate.Range(min=1, max=10))
	582	range_no_upper = fields.Float(validate=validate.Range(min=1))
588	583	multiple_ranges = fields.Int(
589	584	validate=[
590	585	validate.Range(min=1),

610	605	equal_length = fields.Str(
611	606	validate=[validate.Length(equal=5), validate.Length(min=1, max=10)]
612	607	)
	608	date_range = fields.DateTime(
	609	validate=validate.Range(
	610	min=datetime(1900, 1, 1),
	611	)
	612	)
613	613
614	614	@pytest.mark.parametrize(
615	615	("field", "properties"),
616	616	[
617	617	("range", {"minimum": 1, "maximum": 10}),
	618	("range_no_upper", {"minimum": 1}),
618	619	("multiple_ranges", {"minimum": 3, "maximum": 7}),
619	620	("list_length", {"minItems": 1, "maxItems": 10}),
620	621	("custom_list_length", {"minItems": 1, "maxItems": 10}),

622	623	("custom_field_length", {"minLength": 1, "maxLength": 10}),
623	624	("multiple_lengths", {"minLength": 3, "maxLength": 7}),
624	625	("equal_length", {"minLength": 5, "maxLength": 5}),
	626	("date_range", {"x-minimum": datetime(1900, 1, 1)}),
625	627	],
626	628	)
627	629	def test_properties(self, field, properties, spec):

-0

tests/test_yaml_utils.py less more

25	25	@pytest.mark.parametrize("docstring", (None, "", "---"))
26	26	def test_load_operations_from_docstring_empty_docstring(docstring):
27	27	assert yaml_utils.load_operations_from_docstring(docstring) == {}
	28
	29
	30	def test_dict_to_yaml_unicode():
	31	assert yaml_utils.dict_to_yaml({"가": "나"}) == '"\\uAC00": "\\uB098"\n'
	32	assert yaml_utils.dict_to_yaml({"가": "나"}, {"allow_unicode": True}) == "가: 나\n"

-0

tests/utils.py less more

20	20	return spec.to_dict()["components"]["parameters"]
21	21
22	22
	23	def get_headers(spec):
	24	if spec.openapi_version.major < 3:
	25	return spec.to_dict()["headers"]
	26	return spec.to_dict()["components"]["headers"]
	27
	28
23	29	def get_examples(spec):
24	30	return spec.to_dict()["components"]["examples"]
25	31

-5

tox.ini less more

0	0	[tox]
1	1	envlist=
2	2	lint
3		py{35,36,37,38}-marshmallow2
4		py{35,36,37,38}-marshmallow3
	3	py{36,37,38,39}-marshmallow3
5	4	py38-marshmallowdev
6	5	docs
7	6
8	7	[testenv]
9	8	extras = tests
10	9	deps =
11		marshmallow2: marshmallow>=2.0.0,<3.0.0
12		marshmallow3: marshmallow>=3.0.0,<4.0.0
	10	marshmallow3: marshmallow>=3.10.0,<4.0.0
13	11	marshmallowdev: https://github.com/marshmallow-code/marshmallow/archive/dev.tar.gz
14	12	commands = pytest {posargs}
15	13

27	25	[testenv:watch-docs]
28	26	deps = sphinx-autobuild
29	27	extras = docs
30		commands = sphinx-autobuild --open-browser docs/ docs/_build {posargs} -z src/apispec -s 2
	28	commands = sphinx-autobuild --open-browser docs/ docs/_build {posargs} --watch src/apispec --delay 2
31	29
32	30	[testenv:watch-readme]
33	31	deps = restview