Response

Use Blueprint.response to specify a status code and a Schema class or instance to serialize the response.

In the following examples, the GET and PUT methods return an instance of Pet serialized with PetSchema:

@blp.route('/<pet_id>')
class PetsById(MethodView):

    @blp.response(200, PetSchema)
    def get(self, pet_id):
        return Pet.get_by_id(pet_id)

    @blp.arguments(PetSchema)
    @blp.response(200, PetSchema)
    def put(self, update_data, pet_id):
        pet = Pet.get_by_id(pet_id)
        pet.update(update_data)
        return pet

Here, the DELETE returns an empty response so no schema is specified.

@blp.route('/<pet_id>')
class PetsById(MethodView):

    @blp.response(204)
    def delete(self, pet_id):
        Pet.delete(pet_id)

If a view function returns a list of objects, the Schema must be instanciated with many=True.

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

    @blp.response(200, PetSchema(many=True))
    def get(self, args):
        return Pet.get()

Note

If a view function returns a werkzeug.BaseResponse, that response object is returned unchanged: it is not dumped by the schema and the status code is not applied.

Note

If a view function returns a tuple containing a status code, this status code is used in place of the one specified as response parameter. Doing this is generally a bad idea because the response status code won’t match the code in the API documentation.

Documenting Alternative Responses

The Blueprint.response decorator is meant to generate and document the response corresponding to the “normal” flow of the function. There can be alternative flows, if the function raises an exception, which results in a HTTPException, or if it returns a Response object which is returned as is.

Those alternative responses can be documented using the Blueprint.alt_response decorator. Its signature is the same as response but its parameters are only used to document the response.

A view function may only be decorated once with response but can be decorated multiple times with nested alt_response.