How to add individual descriptions for HTTP methods in flask_restx Swagger documentation

Other Questions API
1

I’m working on a Flask application with flask_restx and trying to customize my Swagger documentation. Here’s my current setup:

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

api_blueprint = Blueprint('store_api', __name__)
api = Api(api_blueprint)

store_ns = Namespace('store', description='Store management operations')

@store_ns.route('/inventory_sync', doc={"description": "Store inventory synchronization operations"})
class StoreInventorySync(Resource):

    @store_ns.doc('get_inventory_sync_status')
    @store_ns.response(200, 'Success')
    def get(self):
        logger.info(f"Inventory sync status requested")
        ...
        return {"message": "Inventory sync in progress..."}

    @store_ns.doc('start_inventory_sync', params={'notify_url': {'description':'Notification URL', 'type':'string'}})
    @store_ns.response(200, 'Success')
    def post(self):
        logger.info(f"Inventory sync initiated")
        ...
        return {"message": "Inventory sync process started"}

api.add_namespace(store_ns, path='/store')

I can successfully set descriptions for the namespace and the route class, but both HTTP methods (GET and POST) show the same description in Swagger. I need each method to have its own unique description. For instance, I want different descriptions for GET /store/inventory_sync and POST /store/inventory_sync. Right now they both display the same text from the route decorator. Is there a way to specify individual descriptions for each HTTP method using flask_restx decorators?

2

You can add individual descriptions for each HTTP method by including the description parameter directly in the @store_ns.doc() decorator for each method. Remove the doc parameter from the route decorator and apply it to each method separately.

Here’s how to modify your code:

@store_ns.route('/inventory_sync')
class StoreInventorySync(Resource):

    @store_ns.doc('get_inventory_sync_status', description='Check current inventory synchronization status')
    @store_ns.response(200, 'Success')
    def get(self):
        logger.info(f"Inventory sync status requested")
        return {"message": "Inventory sync in progress..."}

    @store_ns.doc('start_inventory_sync', description='Initiate inventory synchronization process', params={'notify_url': {'description':'Notification URL', 'type':'string'}})
    @store_ns.response(200, 'Success')
    def post(self):
        logger.info(f"Inventory sync initiated")
        return {"message": "Inventory sync process started"}

The key change is moving the description from the route level to each individual method decorator. This way Swagger will display distinct descriptions for GET and POST operations on the same endpoint.

3

yep, just shift the description to each method’s @doc decorator. the route’s desc is shared among methods. use @store_ns.doc('method_name', description='your desc here') for each get/post method and ditch the doc from @route. that should do it!