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?

If you want to add a separate description to each method of a resource, you can do this using the description attribute within the @api.doc() decorator.

@ns.route('/cache_update')
class LocationCacheUpdate(Resource):
    @ns.doc('get_location_cache_update_progress', description='Place your description here!')
    @ns.response(200, 'Success')
    def get(self):
        # ...
        return {'status': 'Location cache updating'}
    
    # ...