如何为Django drf_yasg自定义ViewSet的list响应体添加Swagger描述

我来帮你搞定这个问题——要给自定义的响应体添加清晰的描述，你只需要在Schema对象里补充几个关键参数就行，直接看调整后的代码：

from drf_yasg.openapi import Schema, TYPE_OBJECT, TYPE_STRING, TYPE_ARRAY, TYPE_INTEGER
from drf_yasg.utils import swagger_auto_schema
from rest_framework import viewsets, Response

class StudentViewSet(viewsets.ModelViewSet):
    # 假设你的序列化器是StudentSerializer，这里可以根据实际情况替换
    serializer_class = StudentSerializer

    @swagger_auto_schema(
        responses={
            200: Schema(
                type=TYPE_OBJECT,
                description="自定义的学生列表响应，包含完整的学生数据数组",
                properties={
                    'students': Schema(
                        type=TYPE_ARRAY,
                        description="所有学生对象组成的数组",
                        items=Schema(
                            type=TYPE_OBJECT,
                            description="单个学生的详细信息",
                            properties={
                                'id': Schema(type=TYPE_INTEGER, description="学生的唯一标识ID"),
                                'name': Schema(type=TYPE_STRING, description="学生的姓名"),
                                'age': Schema(type=TYPE_INTEGER, description="学生的年龄"),
                                # 这里可以添加你模型里其他字段的描述，和序列化器对应
                            }
                        )
                    )
                }
            )
        }
    )
    def list(self, request, *args, **kwargs):
        queryset = self.filter_queryset(self.get_queryset())
        page = self.paginate_queryset(queryset)
        if page is not None:
            serializer = self.get_serializer(page, many=True)
            return self.get_paginated_response(serializer.data)
        serializer = self.get_serializer(queryset, many=True)
        return Response({'students': serializer.data})

关键调整说明： #

• 整个响应对象的描述：给最外层的Schema添加description参数，直接说明这个响应的用途。
• 字段级别的描述：通过properties定义响应体里的每个字段，每个字段对应的Schema也可以加description，解释字段的含义。
• 数组元素的描述：对于students这种数组类型的字段，用items参数定义数组里单个元素的结构，同样可以给元素和元素的每个子字段添加描述。

额外提示：处理分页场景 #

如果你的接口开启了分页（代码里的get_paginated_response分支），返回的结构会包含count、next、previous、results这些字段，这时候需要调整Schema来匹配分页响应：

@swagger_auto_schema(
    responses={
        200: Schema(
            type=TYPE_OBJECT,
            description="分页后的学生列表响应",
            properties={
                'count': Schema(type=TYPE_INTEGER, description="系统中所有学生的总数量"),
                'next': Schema(type=TYPE_STRING, description="下一页的接口URL，没有下一页时为null"),
                'previous': Schema(type=TYPE_STRING, description="上一页的接口URL，没有上一页时为null"),
                'results': Schema(
                    type=TYPE_ARRAY,
                    description="当前页展示的学生对象数组",
                    items=Schema(
                        type=TYPE_OBJECT,
                        description="单个学生的详细信息",
                        properties={
                            'id': Schema(type=TYPE_INTEGER, description="学生的唯一标识ID"),
                            'name': Schema(type=TYPE_STRING, description="学生的姓名"),
                        }
                    )
                )
            }
        )
    }
)

这样调整后，Swagger文档里就会清晰展示你自定义响应体的结构和每个部分的描述了。

内容的提问来源于stack exchange，提问作者Ahmadreza