Search code examples
djangodjango-rest-frameworkswaggerdrf-yasgredoc

How to group swagger API endpoints (Function Based Views) with drf_yasg - Django

I am doing some migration work from Django 1.11 --> 3.1.5

previously with "rest_framework_swagger", I am able to accomplish swagger api grouping just by this in url.py

url(r'^api/v9/test_token1$', 
    api.test_token, 
    name='test_token'),

url(r'^api/v9/test_token2$', 
    api.test_token, 
    name='test_token'),

and get this (notice it groups v9)

enter image description here

However, I have tried with "drf_yasg" on Django 3.1.5 url.py

path('/v2/token_api1', token_api1, name='token_api1'),
path('/v2/token_api2', token_api2, name='token_api2'),

my api definition (do note I am using @api_view)

token = openapi.Parameter('token', openapi.IN_FORM, type=openapi.TYPE_STRING, required=True)
@swagger_auto_schema(
    method="post",
    manual_parameters=[token],
    operation_id="token_api1"
)
@api_view(['POST'])
# this is optional and insures that the view gets formdata
@parser_classes([FormParser])
def token_api1(request):
    token = request.POST['token']    
    return Response("success test_api:" + token, status=status.HTTP_200_OK)


token = openapi.Parameter('token', openapi.IN_FORM, type=openapi.TYPE_STRING, required=True)
@swagger_auto_schema(
    method="post",
    manual_parameters=[token],
    operation_id="token_api2"
)
@api_view(['POST'])
# this is optional and insures that the view gets formdata
@parser_classes([FormParser])
def token_api2(request):
    token = request.POST['token']
    return Response("success test_api:" + token, status=status.HTTP_200_OK)

however, I get this (noticed v2 does not group). And also when I did a test, there were errors as well. (Code 404 Error: Not Found)

enter image description here

How can I group these to API in drf_yasg and also making sure there is no error ? Note if the url.py is like this, there is NO error but it does not group

path('token_api1', token_api1, name='token_api1'),
path('token_api2', token_api2, name='token_api2'),
Solution

  • The name is used for accessing endpoints from your Django / Python code. so I believe the newer versions of Django forbid duplicate names.

    You can group your endpoint by supplying them the same tag under tags. like so:

    @swagger_auto_schema(tags=["my_custom_tag"], auto_schema=NoPagingAutoSchema, filter_inspectors=[DjangoFilterDescriptionInspector])
@action(detail=False, methods=['get'])
def action1(self, request):
    pass


@swagger_auto_schema(tags=["my_custom_tag"], method='delete', manual_parameters=[openapi.Parameter(
    name='delete_form_param', in_=openapi.IN_FORM,
    type=openapi.TYPE_INTEGER,
    description="this should not crash (form parameter on DELETE method)"
)])
@action(detail=True, methods=['delete'])
def action2(self, request, slug=None):
    pass

    note that you can also supply several tags for each function thus they will show in several different categories (or groups).

    result:

    enter image description here