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?

Emelinaemeline

django-rest-swagger is no longer being maintained. use drf-yasg – Clambake

the Question should be modified – Smug

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)

Midsummer

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.

Smug

Answer 3

1. of everything please use drf-yasg for documentation .

2. you can find its implementation in one of my repository Kirpi and learn how to use that.

3. if you in 3. ; have question,let me know.

Teamwork