Support multiple schemas in @response?

[anilravuri]

This is a requirement we had in our team where we have a different set of responses (thus multiple schemas) for a given endpoint. I tried marshmallow-oneofschema but that does not seem to work. Any thoughts on this?

[miguelgrinberg]

I don't consider the idea of multiple schemas a good API design practice, so I really have no direct experience (or interest) in implementing this. But marshmallow supports nesting schemas, which may give you something close to what you need. Or else you can hand modify the OpenAPI data structure in a process_apispec callback and make it be exactly what you need.

[sgavil]

@miguelgrinberg What would be the approach if I wanted to return a schema if everything goes well but some kind of failed schema if something goes wrong?

[miguelgrinberg]

@sgavil Your question makes me think that you think APIFairy somehow prevents you from returning an error response based on a schema. This is actually incorrect, you can return anything you want in an error handler, including a serialized Marshmallow schema.

In terms documenting your error schemas, see the @other_responses decorator.

[sersorrel]

The thing that trips me up with this is that, say you have a flask-httpauth error handler which might return a 401, 403, whatever, and you apply this flask-httpauth object to a route with @apifairy.authenticate: now you must also remember to apply @apifairy.other_responses to the route to show what the error handler could return, and you have to do this for every route you use the error handler on. That makes it very easy to forget the @apifairy.other_responses and accidentally give the impression that a route will never fail, when really it can return the same authentication failures as any of your other authenticated routes, and makes it very difficult to ever change what your error handler produces, because you would have to update the @other_response decorator on every route it is used on.

[miguelgrinberg]

@sersorrel You can create your own custom authentication decorator that passes all its arguments through to apifairy.authenticate and also includes apifairy.other_responses with the set of canned error responses you'd like all your authenticated endpoints to have.

[sgavil]

@miguelgrinberg But if I add the @response with a schema and then I return a different failure schema, the failure schema gets converted into the schema I've specified in the response decorator. Am I doing something wrong?

[miguelgrinberg]

@sgavil Yes, you should return your error responses in an error handler, not in the route function.