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. This method can be passed a reference to a registered response component (see Document Top-level Components) or elements to build the response documentation like Blueprint.response does.

The success argument (default: False) indicates whether the response is part of the normal flow of the program or an aborted response. In the former case, processing from other decorators such as pagination or ETag apply and are documented for the status code of the response. The default case is typically used for error conditions that trigger an exception aborting the function.

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