DRF YASG Customizing

Question

I'm trying to customize my api documentation buuild with yasg.

First off, I would like to determine the naming of my own sections, and what endpoints should be included in this section. It seems that the naming of sections is based on the first prefix not belonging to the longest common prefix e.g.:

if we have the urls api/v1/message and api/v1/test than the sections will be named message and test. Is there a way for me to determine A custom naming for this section?

Furthermore, the introduction of every section is empty, how do I add text here?

And last but not least, Stripe has these amazing section dividers how can I add these in drf yasg.

Answer 1

Currently, I'm using APIView and @swagger_auto_schema to define the documentation of my endpoint.

In the code below, you can see how to add more information to define your endpoint. I hope it helps you

##serializers.py

class CategorySerializer(serializers.ModelSerializer):
    """
    Serializing Categories 
    """
    class Meta:
        model = Category
        fields = [
            'id', 'name', 'slug'
        ]
        read_only_fields = [
           'slug', 
        ]


##views.py

username_param = openapi.Parameter('username', in_=openapi.IN_QUERY, description='Username',
                                type=openapi.TYPE_STRING)
email = openapi.Parameter('email', in_=openapi.IN_QUERY, description='Email',
                                type=openapi.TYPE_STRING)  
category_response = openapi.Response('response description', CategorySerializer)    

class CategoryList(APIView):
    permission_classes = [AllowAny]
          
    @swagger_auto_schema(
        manual_parameters=[username_param, email],
        query_serializer=CategorySerializer,
        responses = {
            '200' : category_response,
            '400': 'Bad Request'
        },        
        security=[],
        operation_id='List of categories',
        operation_description='This endpoint does some magic',
    )
    def get(self, request, format=None):
        """
        GET:
        Return a list of all the existing categories.
        """
        categories = Category.objects.all()
        serializer = CategorySerializer(categories, many=True)
        return Response(serializer.data)


    @swagger_auto_schema(
        request_body=CategorySerializer,
        query_serializer=CategorySerializer,
        responses={
            '200': 'Ok Request',
            '400': "Bad Request"
        },
        security=[],
        operation_id='Create category',
        operation_description='Create of categories',
    )
    def post(self, request, format=None):
        """
        POST:
        Create a new category instance.
        """
        serializer = CategorySerializer(data=request.data)
        if serializer.is_valid():
            serializer.save(created_by=self.request.user)
            return Response(serializer.data, status=status.HTTP_201_CREATED)
        return Response(serializer.errors, status=status.HTTP_400_BAD_REQUEST)

By last, if you want to see your endpoints in groups by link, you can test commenting the line below in yours urls.py

#urlpatterns = format_suffix_patterns(urlpatterns)

Below, some screen of how you should see it

You can find more information in the following link: https://drf-yasg.readthedocs.io/en/stable/custom_spec.html