Arguments

To inject arguments into a view function, use the Blueprint.arguments decorator. It allows to specify a Schema to deserialize and validate the parameters.

When processing a request, the input data is deserialized, validated, and injected in the view function.

@blp.route('/')
class Pets(MethodView):

    @blp.arguments(PetQueryArgsSchema, location='query')
    @blp.response(PetSchema(many=True))
    def get(self, args):
        return Pet.get(filters=args)

    @blp.arguments(PetSchema)
    @blp.response(PetSchema, code=201)
    def post(self, pet_data):
        return Pet.create(**pet_data)

Arguments Location

The following locations are allowed:

  • "json"
  • "query" (or "querystring")
  • "path"
  • "form"
  • "headers"
  • "cookies"
  • "files"

The location defaults to "json", which means body parameter.

Note

Blueprint.arguments uses webargs’s use_args decorator internally, but unlike use_args, it only accepts a single location.

Arguments Injection

By default, arguments are passed as a single positional dict argument. If as_kwargs=True is passed, the decorator passes deserialized input data as keyword arguments instead.

@blp.route('/')
class Pets(MethodView):

    @blp.arguments(PetQueryArgsSchema, location='query', as_kwargs=True)
    @blp.response(PetSchema(many=True))
    def get(self, **kwargs):
        return Pet.get(filters=**kwargs)

This decorator can be called several times on a resource function, for instance to accept both body and query parameters. The order of the decorator calls matters as it determines the order in which the parameters are passed to the view function.

@blp.route('/')
class Pets(MethodView):

    @blp.arguments(PetSchema)
    @blp.arguments(QueryArgsSchema, location='query')
    def post(pet_data, query_args):
        return Pet.create(pet_data, **query_args)

Content Type

When using body arguments, a default content type is assumed depending on the location. The location / content type mapping can be customized by modifying Blueprint.DEFAULT_LOCATION_CONTENT_TYPE_MAPPING.

DEFAULT_LOCATION_CONTENT_TYPE_MAPPING = {
    "json": "application/json",
    "form": "application/x-www-form-urlencoded",
    "files": "multipart/form-data",

It is also possible to override those defaults in a single resource by passing a string as content_type argument to Blueprint.arguments.

Note

The content type is only used for documentation purpose and has no impact on request parsing.

Note

Multipart requests with mixed types (file, form, etc.) are not supported. They can be achieved but the documentation is not correctly generated. arguments decorator can be called multiple times on the same view function but it should not be called with more that one request body location. This limitation is discussed in #46.

File Upload

File uploads as multipart/form-data are supported for both OpenAPI 3 and OpenAPI 2.

The arguments Schema should contain Upload fields. The files are injected in the view function as a dict of werkzeug FileStorage instances.

from werkzeug.utils import secure_filename
from flask_rest_api.fields import Upload

class MultipartFileSchema(ma.Schema):
    file_1 = Upload()

@blp.route('/', methods=['POST'])
@blp.arguments(MultipartFileSchema, location='files')
@blp.response(code=201)
def func(files):
    base_dir = '/path/to/storage/dir/'
    file_1 = files['file_1']
    file_1.save(secure_filename(file_1.filename))