django-rest-swagger nested serializers with readonly fields not rendered properly

Question

I'm building an API with django-rest-framework and I started using django-rest-swagger for documentation. I have a nested serializer with some read_only fields, like this:

# this is the nested serializer
class Nested(serializers.Serializer):
    normal_field = serializers.CharField(help_text="normal")
    readonly_field = serializers.CharField(read_only=True,
                                           help_text="readonly")

# this is the parent one
class Parent(serializers.Serializer):
    nested_field = Nested()

In the generated docs, nested serializers in the Parameters part of the page are rendered with field data type and no hint is given about its content, they are just like other fields.

Now you can see the problem there, as I would like to inform the user that there is a readonly field that should not be sent as part of the nested data but I can not see a way of doing so.

The ideal would be having a model description in Data Type column, just like the Response Class section.

Is there any proper way of doing so?

Answer 1

Try to use drf_yasg instead, Swagger will generate the documentation for APIs, but it's not absolutely right! If you want to correct Swagger documentation, you can do it. You will need to use swagger_auto_schema decorator. Below is the sample code:

from drf_yasg import openapi
from drf_yasg.utils import swagger_auto_schema

class ProductSuspendView(CreateAPIView):

    @swagger_auto_schema(
        tags=['dashboard'],
        request_body=openapi.Schema(
            type=openapi.TYPE_OBJECT,
            properties={
                'id': openapi.Schema(
                    type=openapi.TYPE_INTEGER,
                    description='Id',
                ),
                'suspend_kinds': openapi.Schema(
                    type=openapi.TYPE_ARRAY,
                    items=openapi.Items(type=openapi.TYPE_INTEGER),
                    description='Array suspend (Inappropriate image: 1, Insufficient information: 2,  Bad language: 3) (suspend_kinds=[1,2])'
                ),
            }
        ),
        responses={
            status.HTTP_200_OK: SuccessResponseSerializer,
            status.HTTP_400_BAD_REQUEST: ErrorResponseSerializer
        }
    )
    def post(self, request, *args, **kwargs):
        """
        Suspend a product.
        """
        ...
        if success:
            return Response({'success': True}, status.HTTP_200_OK)

        return Response({'success': False}, status.HTTP_400_BAD_REQUEST)

Answer 2

Using https://drf-spectacular.readthedocs.io/en/latest/ would be the right choice for this use case now. this is well maintained and support OpenAPI 3.0+. also it is now suggested by django-rest-framework itself.