<commit_before>Documenting your API with Swagger
=================================

A Swagger API documentation is automatically generated and available on your API root
but you need to provide some details with the ``@api.doc()`` decorator.


Documenting with the ``@api.doc()`` decorator
---------------------------------------------

This decorator allows you specify some details about your API.
They will be used in the Swagger API declarations.

You can document a class or a method.


.. code-block:: python

    @api.route('/my-resource/<id>', endpoint='my-resource')
    @api.doc(params={'id': 'An ID'})
    class MyResource(Resource):
        def get(self, id):
            return {}

        @api.doc(responses={403: 'Not Authorized'})
        def post(self, id):
            api.abort(403)


Documenting with the ``@api.model()`` decorator
-----------------------------------------------

The ``@api.model`` decorator allows you to declare the models that your API can serialize.

You can also extend fields and use the ``__schema_format__`` and ``__schema_type__``
to specify the produced types:

.. code-block:: python

    my_fields = api.model('MyModel', {
        'name': fields.String,
        'age': fields.Integer(min=0)
    })

    class MyIntField(fields.Integer):
        __schema_format__ = 'int64'

    class MySpecialField(fields.Raw):
        __schema_type__ = 'some-type'
        __schema_format__ = 'some-format'



Duplicating with ``api.extend``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The ``api.extend`` method allows you to register an augmented model.
It saves you duplicating all fields.

.. code-block:: python

    parent = api.model('Parent', {
        'name': fields.String
    })

    child = api.extend('Child', parent, {
        'age': fields.Integer
    })


Polymorphism with ``api.inherit``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The ``api.inherit`` method allows to extend a model in the "Swagger way"
and to start handling polymorphism.
It will register both the parent and the child in the Swagger models definitions.

.. code-block:: python

    parent = api.model('Parent', {
        'name': fields.String,
        'class': fields.String(discriminator=True)
    })

    child = api.inherit('Child', parent, {
        'extra': fields.String
    })

Will produce the following Swagger definitions:

.. code-block:: json

    "Child": {
        "properties": {
            "name": {"type": "string"},
            "class": {"type": "string"}
        },
        "discriminator": "class",
        "required": ["class"]
    },
    "Child": {
        "allOf": [{
                "$ref": "#/definitions/Parent"
            }, {
                "properties": {
                    "extra": {"type": "string"}
                }
            }
        ]
    }

The ``class`` field in this example will be populated with the serialized model name
only if the property does not exists in the serialized object.

The ``Polymorph`` field allows you to specify a mapping between Python classes
and fields specifications.

.. code-block:: python

    mapping = {
        Child1: child1_fields,
        Child2: child2_fields,
    }

    fields = api.model('Thing', {
        owner: fields.Polymorph(mapping)
    })


Documenting with the ``@api.marshal_with()`` decorator
------------------------------------------------------

This decorator works like the Flask-Restful ``marshal_with`` decorator
with the difference that it documents the methods.
The optionnal parameter ``as_list`` allows you to specify wether or not the objects are returned as a list.

.. code-block:: python

    resource_fields = api.model('Resource', {
        'name': fields.String,
    })

    @api.route('/my-resource/<id>', endpoint='my-resource')
    class MyResource(Resource):
        @api.marshal_with(resource_fields, as_list=True)
        def get(self):
            return get_objects()

        @api.marshal_with(resource_fields)
        def post(self):
            return create_object()


The ``@pi.marshal_list_with()`` decorator is strictly equivalent to ``Api.marshal_with(fields, as_list=True)``.

.. code-block:: python

    resource_fields = api.model('Resource', {
        'name': fields.String,
    })

    @api.route('/my-resource/<id>', endpoint='my-resource')
    class MyResource(Resource):
        @api.marshal_list_with(resource_fields)
        def get(self):
            return get_objects()

        @api.marshal_with(resource_fields)
        def post(self):
            return create_object()


Documenting with the ``@api.expect()`` decorator
------------------------------------------------

The ``@api.expect()`` decorator allows you to specify the expected input fields
and is a shortcut for ``@api.doc(body=<fields>)``.<commit_msg>Fix typo<commit_after>Documenting your API with Swagger
=================================

A Swagger API documentation is automatically generated and available on your API root
but you need to provide some details with the ``@api.doc()`` decorator.


Documenting with the ``@api.doc()`` decorator
---------------------------------------------

This decorator allows you specify some details about your API.
They will be used in the Swagger API declarations.

You can document a class or a method.


.. code-block:: python

    @api.route('/my-resource/<id>', endpoint='my-resource')
    @api.doc(params={'id': 'An ID'})
    class MyResource(Resource):
        def get(self, id):
            return {}

        @api.doc(responses={403: 'Not Authorized'})
        def post(self, id):
            api.abort(403)


Documenting with the ``@api.model()`` decorator
-----------------------------------------------

The ``@api.model`` decorator allows you to declare the models that your API can serialize.

You can also extend fields and use the ``__schema_format__`` and ``__schema_type__``
to specify the produced types:

.. code-block:: python

    my_fields = api.model('MyModel', {
        'name': fields.String,
        'age': fields.Integer(min=0)
    })

    class MyIntField(fields.Integer):
        __schema_format__ = 'int64'

    class MySpecialField(fields.Raw):
        __schema_type__ = 'some-type'
        __schema_format__ = 'some-format'



Duplicating with ``api.extend``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The ``api.extend`` method allows you to register an augmented model.
It saves you duplicating all fields.

.. code-block:: python

    parent = api.model('Parent', {
        'name': fields.String
    })

    child = api.extend('Child', parent, {
        'age': fields.Integer
    })


Polymorphism with ``api.inherit``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The ``api.inherit`` method allows to extend a model in the "Swagger way"
and to start handling polymorphism.
It will register both the parent and the child in the Swagger models definitions.

.. code-block:: python

    parent = api.model('Parent', {
        'name': fields.String,
        'class': fields.String(discriminator=True)
    })

    child = api.inherit('Child', parent, {
        'extra': fields.String
    })

Will produce the following Swagger definitions:

.. code-block:: json

    "Child": {
        "properties": {
            "name": {"type": "string"},
            "class": {"type": "string"}
        },
        "discriminator": "class",
        "required": ["class"]
    },
    "Child": {
        "allOf": [{
                "$ref": "#/definitions/Parent"
            }, {
                "properties": {
                    "extra": {"type": "string"}
                }
            }
        ]
    }

The ``class`` field in this example will be populated with the serialized model name
only if the property does not exists in the serialized object.

The ``Polymorph`` field allows you to specify a mapping between Python classes
and fields specifications.

.. code-block:: python

    mapping = {
        Child1: child1_fields,
        Child2: child2_fields,
    }

    fields = api.model('Thing', {
        owner: fields.Polymorph(mapping)
    })


Documenting with the ``@api.marshal_with()`` decorator
------------------------------------------------------

This decorator works like the Flask-Restful ``marshal_with`` decorator
with the difference that it documents the methods.
The optionnal parameter ``as_list`` allows you to specify wether or not the objects are returned as a list.

.. code-block:: python

    resource_fields = api.model('Resource', {
        'name': fields.String,
    })

    @api.route('/my-resource/<id>', endpoint='my-resource')
    class MyResource(Resource):
        @api.marshal_with(resource_fields, as_list=True)
        def get(self):
            return get_objects()

        @api.marshal_with(resource_fields)
        def post(self):
            return create_object()


The ``@api.marshal_list_with()`` decorator is strictly equivalent to ``Api.marshal_with(fields, as_list=True)``.

.. code-block:: python

    resource_fields = api.model('Resource', {
        'name': fields.String,
    })

    @api.route('/my-resource/<id>', endpoint='my-resource')
    class MyResource(Resource):
        @api.marshal_list_with(resource_fields)
        def get(self):
            return get_objects()

        @api.marshal_with(resource_fields)
        def post(self):
            return create_object()


Documenting with the ``@api.expect()`` decorator
------------------------------------------------

The ``@api.expect()`` decorator allows you to specify the expected input fields
and is a shortcut for ``@api.doc(body=<fields>)``.
{'fraction_non_alphanumeric': 0.17755831056944738, 'fraction_numerical': 0.0027316663164530363, 'mean_word_length': 2.458938953488372, 'pattern_counts': {'":': 28, '<': 11, '<?xml version=': 0, '>': 11, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2086539', 'n_tokens_mistral': 2663, 'n_tokens_neox': 2557, 'n_words': 802}