----------------------------------------------------------------------------------------------------------------------------------------------------------+
| ``schemas``                 | The Schema Object allows the definition of input and output data types. Maps to the ```schema`` <http://swagger.io/specification/#schemaObject>`__                                                                                                                                                                                                                                                                       |
+-----------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| ``content``                 | A list of MIME types the API can consume. Maps to the ```contents`` <http://swagger.io/specification/#contentObject>`__ field of the `components <http://swagger.io/specification/#componentObject>`__.                                                                                                                                                                                                                  |
+-----------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| ``contact``                 | The contact information for the API. Maps to the ``contact`` field of the `info object <http://swagger.io/specification/#infoObject>`__.                                                                                                                                                                                                                                                                                 |
+-----------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| ``description``             | A short description of the application. Maps to the ``description`` field of the `info object <http://swagger.io/specification/#infoObject>`__.                                                                                                                                                                                                                                                                          |
+-----------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| ``external_docs``           | Additional external documentation. Maps to the ``externalDocs`` field of the `operation object <http://swagger.io/specification/#operationObject>`__.                                                                                                                                                                                                                                                                    |
+-----------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| ``license``                 | The license information for the API. Maps to the ``license`` field of the `info object <http://swagger.io/specification/#infoObject>`__.                                                                                                                                                                                                                                                                                 |
+-----------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| ``parameters``              | The parameters that can be used across operations. Maps to the ``parameters`` field of the `operation object <http://swagger.io/specification/#operationObject>`__.                                                                                                                                                                                                                                                      |
+-----------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| ``responses``               | The responses that can be used across operations. Maps to the ``responses`` field of the `operation object <http://swagger.io/specification/#operationObject>`__.                                                                                                                                                                                                                                                        |
+-----------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| ``security``                | A declaration of which security mechanisms can be used across the API. The list of values includes alternative security requirement objects that can be used. Only one of the security requirement objects need to be satisfied to authorize a request. Individual operations can override this definition. Maps to the ``security`` field of the `OpenAPI Object <http://swagger.io/specification/#openapiObject>`__.   |
+-----------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| ``securitySchemes``         | The security schemes for the API. Maps to the ``securitySchemes`` field of the `component object <http://swagger.io/specification/#componentsObject>`__.                                                                                                                                                                                                                                                                 |
+-----------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| ``tags``                    | A list of tags used by the specification with additional metadata. Maps to the ``tags`` field fo the `OpenAPI Object <http://swagger.io/specification/#openapiObject>`__.                                                                                                                                                                                                                                                |
+-----------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| ``terms``                   | The terms of service for the API. Maps to the ``termsOfService`` field of the `info object <http://swagger.io/specification/#infoObject>`__.                                                                                                                                                                                                                                                                             |
+-----------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| ``title``                   | The title of the application (defaults to the flask app module name). Maps to the ``title`` field of the `info object <http://swagger.io/specification/#infoObject>`__.                                                                                                                                                                                                                                                  |
+-----------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+

Documenting API endpoints
-------------------------

Decorate your API endpoints with ``@swagger.doc``. It takes a dictionary
in the format of an `operation
object <http://swagger.io/specification/#operationObject>`__.

.. code:: python

    class UserItemResource(Resource):
        @swagger.doc({
            'tags': ['user'],
            'description': 'Returns a user',
            'parameters': [
                {
                    'name': 'user_id',
                    'description': 'User identifier',
                    'in': 'path',
                   'schema': {
                        'type': 'integer'
                    }
                }
            ],
           'responses': {
                '200': {
                    'description': 'User',
                    'content': {
                        'application/json': {
                           'schema': UserModel,
                            'examples': {
                                'application/json': {
                                    'id': 1,
                                    'name':'somebody'
                                }
                            }
                        }
                    }
                }
            }
         })
        def get(self, user_id):
            # Do some processing
            return UserModel(id=1, name='somebody'}), 200  # generates json response {"id": 1, "name": "somebody"}

Use add\_resource as usual.

.. code:: python

    api.add_resource(UserItemResource, '/api/users/<int:user_id>')

Parsing query parameters
------------------------

If a resource function contains the special argument ``_parser``, any
``query`` type parameters in the documentation will be automatically
added to a reqparse parser and assigned to the ``_parser`` argument.

Using models
------------

Create a model by inheriting from ``flask_restful_swagger_3.Schema``

.. code:: python

    from flask_restful_swagger_2 import Schema


    class EmailModel(Schema):
        type ='string'
        format = 'email'


    class KeysModel(Schema):
        type = 'object'
        properties = {
            'name': {
                'type':'string'
            }
        }


    class UserModel(Schema):
        type = 'object'
        properties = {
            'id': {
                'type': 'integer',
                'format': 'int64',
            },
            'name': {
                'type':'string'
            },
           'mail': EmailModel,
            'keys': KeysModel.array()
        }
        required = ['name']

You can build your models according to the `swagger schema object
specification <http://swagger.io/specification/#schemaObject>`__

It is recommended that you always return a model in your views so that
your code and documentation are in sync.

RequestParser support
---------------------

You can specify RequestParser object if you want to pass its arguments
to spec. In such case, there is not need to define model manually

.. code:: python

    from flask_restful.reqparse import RequestParser

    from flask_restful_swagger_2 import swagger, Resource


    class GroupResource(Resource):
        post_parser = RequestParser()
        post_parser.add_argument('name', type=str, required=True)
        post_parser.add_argument('id', type=int, help='Id of new group')
        @swagger.doc({
            'tags': ['groups'],
            'description': 'Adds a group',
           'reqparser': {'name': 'group parser',
                          'parser': post_parser},
           'responses': {
                '201': {
                    'description': 'Created group',
                    'content': {
                        'application/json': {
                            'examples': {
                                'application/json': {
                                    'id': 1
                                }
                            }
                        }
                    }
                }
            }
        })
        def post(self):
       ...

Swagger schema (among other things):

.. code:: json

    {"GroupsModel": {
        "properties": {
            "id": {
                "default": null,
                "description": "Id of new group",
                "name": "id",
                "required": false,
                "type": "integer"
                },
            "name": {
                "default": null,
                "description": null,
                "name": "name",
                "required": true,
                "type": "string"
            }
        },
        "type": "object"
    }

Using authentication
--------------------

In the example above, the view ``UserItemResource`` is a subclass of
``Resource``, which is provided by ``flask_restful``. However,
``flask_restful_swagger_3`` provides a thin wrapper around ``Resource``
to provide authentication. By using this, you can not only prevent
access to resources, but also hide the documentation depending