3

I using Flask-Restplus to develop my API. I wanna to ask,why the @api.doc decorator not update my changes in the Swagger UI?

Here is the endpoint I define 

@api.route('/create_user')
class User(Resource):
    @api.response(201, 'User successfully created.')
    @api.doc('create a new user')
    @api.expect(_user, validate=True)
    @api.marshal_list_with(_user, envelope='data')
    def post(self):
        """Creates a new User """
        data = request.json
        return create_user(data=data)


@api.route('/get_user_list')
class UserList(Resource):
    @api.doc('list_of_registered') //even I change here,in Swagger is still not update
    @api.marshal_list_with(_user, envelope='data')
    def get(self):
        """List all registered users"""
        return get_all_users()

@api.route('/create_product')
class Product(Resource):
    @api.response(201, 'Product successfully created.')
    @api.doc('12345678') //here I state to this
    @api.expect(_product, validate=True)
    def post(self):
        """Creates a new User """
        data = request.json
        return create_product(data=data)

So here is the result in my browser:

enter image description here

As you can see here,the doc is not updating according the string I define in @api.doc decorator.

So anyone can let me know why is this happen? And how to solve this?

ken
  • 2,426
  • 5
  • 43
  • 98

1 Answers1

4

in fact the documentation that it generates first of the comment which follows directly the declaration of your function

change that: 

@api.route('/create_product')
class Product(Resource):
    @api.response(201, 'Product successfully created.')
    @api.doc('12345678') //here I state to this
    @api.expect(_product, validate=True)
    def post(self):
        """Creates a new User """
        data = request.json
        return create_product(data=data)

To that:

@api.route('/create_product')
class Product(Resource):
    @api.response(201, 'Product successfully created.')
    @api.doc('12345678') //here I state to this
    @api.expect(_product, validate=True)
    def post(self):
        """Creates a new Product """
        data = request.json
        return create_product(data=data)
wamba kevin
  • 308
  • 3
  • 9
  • so means that the documentation will generate from the comment in function??If no comment in function,then only it will generate from `@api.doc` am I right?? – ken Jan 25 '19 at 22:51
  • not sorry I was wrong, he only takes this documentation as commentary – wamba kevin Jan 25 '19 at 22:53
  • but when it doesnt have comment in the function,the documentation in browser direct empty,but not generate form api.doc – ken Jan 25 '19 at 22:53
  • yes it's true I just tested and it does not use the one that is specified trought @api.doc – wamba kevin Jan 25 '19 at 22:55
  • you can check the answer to help others who have the same problem – wamba kevin Jan 25 '19 at 22:57
  • I have the same bug using the api.expect or api.doc(body) used by model. Why the model don't updated in documentation? Any idea @wambakevin – Tiago Barreto Mar 01 '19 at 17:41
  • @TiagoBarreto can I see your code to try to find the error? – wamba kevin Mar 03 '19 at 12:12
  • 1
    What I'd really like to know is why I can't even find (easily) in the latest flask-restplus documentation a mention of the fact that the method descriptions are taken from the block comment following the method declaration, let alone how to override that. There's nothing in the [Swagger documentation section](https://flask-restplus.readthedocs.io/en/stable/swagger.html) and I would have thought that a search on "comment" would have turned up something. What am I missing? – flayman Jun 06 '19 at 11:13
  • @flayman This feature is only mentioned in some github issues: https://github.com/noirbizarre/flask-restplus/issues/137, https://github.com/noirbizarre/flask-restplus/issues/215, https://github.com/noirbizarre/flask-restplus/issues/249 It should also be noted that there is a new fork https://flask-restx.readthedocs.io/en/latest/ . – asmaier Jul 03 '20 at 14:36