DRF中Swagger Schema显示错误，如何修正列表返回的API文档？

我定义了如下ViewSet：

class MyViewSet:
    @action(detail=False)
    def statuses(self, *args, **kwargs):
        serializer = self.get_serializer(MyModel.Statuses, many=True)
        return Response(serializer.data)

对应的Serializer：

class LabelValueSerializer(serializers.Serializer):
    label = serializers.CharField()
    value = serializers.CharField()

    class Meta:
        fields = ("label", "value")

接口实际返回的响应是正确的列表格式：

[
  {
    "label": "New",
    "value": "new"
  },
  {
    "label": "Processing",
    "value": "processing"
  },
  {
    "label": "Finished",
    "value": "finished"
  }
]

但Swagger生成的API Schema错误地显示仅返回单个对象，而非列表。需要修正为显示列表格式：

[
  {
    "label": string,
    "value": string
  }
]

方法1：用swagger_auto_schema显式指定列表类型 #

通过swagger_auto_schema装饰器直接告诉Swagger接口返回的是序列化器的列表实例：

from drf_yasg.utils import swagger_auto_schema

class MyViewSet:
    @swagger_auto_schema(responses={200: LabelValueSerializer(many=True)})
    @action(detail=False)
    def statuses(self, *args, **kwargs):
        serializer = self.get_serializer(MyModel.Statuses, many=True)
        return Response(serializer.data)

这个方式能精准控制Swagger显示的响应结构，让它明确识别出这是一个列表而非单个对象。

方法2：给ViewSet指定默认serializer_class #

如果你的ViewSet没设置serializer_class，get_serializer可能无法正确推断序列化器类型，导致Swagger识别错误。给ViewSet加上默认序列化器：

class MyViewSet:
    serializer_class = LabelValueSerializer

    @action(detail=False)
    def statuses(self, *args, **kwargs):
        serializer = self.get_serializer(MyModel.Statuses, many=True)
        return Response(serializer.data)

这样get_serializer结合many=True参数，能让Swagger正确识别响应为列表格式。

方法3：手动构建响应Schema #

如果前两种方法不生效，直接手动定义数组类型的响应结构：

from drf_yasg.utils import swagger_auto_schema
from drf_yasg import openapi

class MyViewSet:
    @swagger_auto_schema(
        responses={
            200: openapi.Response(
                description="状态列表",
                schema=openapi.Schema(
                    type=openapi.TYPE_ARRAY,
                    items=openapi.Schema(
                        type=openapi.TYPE_OBJECT,
                        properties={
                            'label': openapi.Schema(type=openapi.TYPE_STRING),
                            'value': openapi.Schema(type=openapi.TYPE_STRING)
                        }
                    )
                )
            )
        }
    )
    @action(detail=False)
    def statuses(self, *args, **kwargs):
        serializer = self.get_serializer(MyModel.Statuses, many=True)
        return Response(serializer.data)

手动描述Schema的数组和对象结构，确保Swagger生成完全符合预期的文档。

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