带有只读字段的 django-rest-swagger 嵌套序列化程序未正确呈现

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

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.

Answer 2

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)