[SOLVED] Swagger documentation for API response with flask-restx

Swagger documentation for API response with flask-restx

I'm reading the documentation for swagger documentation with flask-restx, and following the examples. I understand that in order to generate swagger docs for the parameters the API takes, I should do

@api.doc(params={'id': 'An ID'})

However, I can't find an explanation of how to document the API's response body. Not the response code, but the result returned by e.g. the get-method. What I'm looking for is something like the below:

class MyResource(Resource):
    @api.doc(returns={"info": "Some very interesting information"})
    def get(self, id):
        res = some_function_of_id(id)
        return {"info": res}

Anyone know if this is possible and if so, how?

Solution

Try api.response decorator

model = api.model('Model', {
    'name': fields.String,
})
@api.route('/my-resource/')
class MyResource(Resource):
    @api.response(200, 'Success', model)
    @api.response(400, 'Validation Error')
    def get(self):
        pass

Note that the @api.marshal_with() decorator automatically documents the response..

https://flask-restx.readthedocs.io/en/latest/swagger.html#documenting-with-the-api-response-decorator