OpenQuizz
Une application de gestion des contenus pédagogiques
apispec.ext.marshmallow Namespace Reference

Namespaces

 common
 
 field_converter
 
 openapi
 
 schema_resolver
 

Data Structures

class  MarshmallowPlugin
 

Functions

def resolver (schema)
 

Detailed Description

marshmallow plugin for apispec. Allows passing a marshmallow
`Schema` to `spec.components.schema <apispec.core.Components.schema>`,
`spec.components.parameter <apispec.core.Components.parameter>`,
`spec.components.response <apispec.core.Components.response>`
(for response and headers schemas) and
`spec.path <apispec.APISpec.path>` (for responses and response headers).

Requires marshmallow>=2.15.2.

``MarshmallowPlugin`` maps marshmallow ``Field`` classes with OpenAPI types and
formats.

It inspects field attributes to automatically document properties
such as read/write-only, range and length constraints, etc.

OpenAPI properties can also be passed as metadata to the ``Field`` instance
if they can't be inferred from the field attributes (`description`,...), or to
override automatic documentation (`readOnly`,...). A metadata attribute is used
in the documentation either if it is a valid OpenAPI property, or if it starts
with `"x-"` (vendor extension).

.. warning::

``MarshmallowPlugin`` infers the ``default`` property from the ``missing``
attribute of the ``Field`` (unless ``missing`` is a callable).
In marshmallow 3, default values are entered in deserialized form,
so the value is serialized by the ``Field`` instance.
This may lead to inaccurate documentation in very specific cases.
The default value to display in the documentation can be
specified explicitly by passing ``doc_default`` as metadata.

::

from pprint import pprint
import datetime as dt

from apispec import APISpec
from apispec.ext.marshmallow import MarshmallowPlugin
from marshmallow import Schema, fields

spec = APISpec(
    title="Example App",
    version="1.0.0",
    openapi_version="3.0.2",
    plugins=[MarshmallowPlugin()],
)


class UserSchema(Schema):
    id = fields.Int(dump_only=True)
    name = fields.Str(metadata={"description": "The user's name"})
    created = fields.DateTime(
        dump_only=True,
        default=dt.datetime.utcnow,
        metadata={"doc_default": "The current datetime"}
    )


spec.components.schema("User", schema=UserSchema)
pprint(spec.to_dict()["components"]["schemas"])
# {'User': {'properties': {'created': {'default': 'The current datetime',
#                                      'format': 'date-time',
#                                      'readOnly': True,
#                                      'type': 'string'},
#                          'id': {'readOnly': True,
#                                 'type': 'integer'},
#                          'name': {'description': "The user's name",
#                                   'type': 'string'}},
#           'type': 'object'}}

Function Documentation

◆ resolver()

def apispec.ext.marshmallow.resolver (   schema)
Default schema name resolver function that strips 'Schema' from the end of the class name.