Swagger documentation for API response with flask-restx

Question

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?

score 0 · Accepted Answer · answered Nov 09 '21 at 08:10

0

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

answered Nov 09 '21 at 08:10

Ammar Aslam

560
2
16

This documents the response codes, not the result returned by the API on a successful call. – bjarkemoensted Nov 09 '21 at 08:42
No it documents the response result as well. I'm passing the model as 3rd parameter, if you pass the model it should be documented – Ammar Aslam Nov 09 '21 at 12:08
here's a picture of me trying it with response code 400: https://imgur.com/AlsSlgl – Ammar Aslam Nov 09 '21 at 12:09
Cannot use with other expected json than objects. – leonard vertighel May 30 '22 at 14:08

Swagger documentation for API response with flask-restx

1 Answers1