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?

Vashtee

Answer 1

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!

Consensual

Answer 2

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!

Galligan