Django, drf-yasg - how to add description to tags?

Question

Swagger documentation says you can do that:

https://swagger.io/docs/specification/grouping-operations-with-tags/

But unfortunately drf-yasg not implementing this feature:

https://github.com/axnsan12/drf-yasg/issues/454

It is said, that I can add custom generator class, but it is a very general answer. Now I see that drf_yasg.openapi.Swagger gets info block and I have thoughts, that this might be right place to put global tags section as an additional init argument, but it deeper, than customizing generator class and I have lack of knowledge of this module

Does anybody have solution to this particular problem, or at least maybe a link to some sort of tutorial, how to properly customize generator class?

Answer 1

Not sure if this is exactly what your are looking for, but I think it might help.

To set tags I use @swagger_auto_schema decorator , which can be applied in a few different ways depending mostly on the type of Views used on your project. Complete details can be found on docs here .

When using Views derived from APIView , you could do something like this:

class ClientView(APIView):
    @swagger_auto_schema(tags=['my custom tag'])
    def get(self, request, client_id=None):
        pass

According to the docs , the limitation is that tags only takes a list of strs as value. So from here on, I believe there is no support for extra attributes over tags as stated at Swagger docs, here .

Anyway, if you only need to define a summary or a description to obtain something like the image below, you could define them using the decorator or a class-level docstring. Here is an example:

class ClientView(APIView):
    '''
    get:
    Client List serialized as JSON.

    This is a description from a class level docstring.

    '''
    def get(self, request, client_id=None):
        pass
    
    @swagger_auto_schema(
        operation_description="POST description override using 
            decorator",
        operation_summary="this is the summary from decorator",
        
        # request_body is used to specify parameters
        request_body=openapi.Schema(
            type=openapi.TYPE_OBJECT,
            required=['name'],
            properties={
                'name': openapi.Schema(type=openapi.TYPE_STRING),
            },
        ),
        tags=['my custom tag']
    )
    def post(self, request):
        pass

Good luck!

Answer 2

Unfortunately, this is a current issue with drf-yasg.

To actually achieve this, you need to create your own schema generator class:

from drf_yasg.generators import OpenAPISchemaGenerator

class CustomOpenAPISchemaGenerator(OpenAPISchemaGenerator):
  def get_schema(self, request=None, public=False):
    """Generate a :class:`.Swagger` object with custom tags"""

    swagger = super().get_schema(request, public)
    swagger.tags = [
        {
            "name": "api",
            "description": "everything about your API"
        },
        {
            "name": "users",
            "description": "everything about your users"
        },
    ]

    return swagger

Make sure to also include it in your Schema View

from drf_yasg.views import get_schema_view
from drf_yasg import openapi

schema_view = get_schema_view(
  openapi.Info(
    title="My API",
    default_version='v1',
  ),
  generator_class=CustomOpenAPISchemaGenerator,
)

Hope this works for you!