[Python] Show description of each API endpoint method for Swagger doc with flask_restx

I have something like this for my Flask app using flask_restx:

from flask import Blueprint, request
from flask_restx import Api, Resource, Namespace

blueprint = Blueprint('location_api', __name__)
api = Api(blueprint)

ns = Namespace('location', description='Location update operations')

@ns.route('/cache_update', doc={"description": "Location cache update operations"})
class LocationCacheUpdate(Resource):

@ns.doc('get_location_cache_update_progress')
@ns.response(200, 'Success')
def get(self):
logger.info(f"Location cache update progress requested")
...
return {"status": "Location cache updating..."}


@ns.doc('post_location_cache_update', params={'callback': {'description':'Callback URL', 'type':'string'}})
@ns.response(200, 'Success')
def post(self):
logger.info(f"Location cache update requested")
...
return {"status": "Location cache update has started"}

api.add_namespace(ns, path='/location')



This utilises the Namespace decorators of flask_restx to help generating the swagger doc for me. Note @ns.doc(...) in the code above each class function.

In the swagger doc, I manage to have a description displayed for each namesapce (using ns = Namespace('location', description='...') ) and the same description displayed for all the endpoints under class LocationCacheUpdate (using @ns.route(doc={"description": "..."}) ). However, I want to have different description for each method (each function under class LocationCacheUpdate) but I just don't see how that can be achieved.

For example, in the swagger doc, I would expect to have different descriptions for each of these:

• GET /location/cache_update
• POST /location/cache_update

But at the moment, these all share the same description. I can't find where this is documented. Is there a Namespace decorator/function I can take advantage of?

Continue reading...