DRF-Spectacular 中如何正确处理非分页列表响应

在使用 DRF-Spectacular 为 Django REST Framework 生成 API 文档时，开发者可能会遇到一个常见问题：即使视图本身没有启用分页，使用 many=True 的序列化器在生成的 Swagger 文档中仍然显示为分页响应格式。本文将深入分析这一现象的原因，并提供多种解决方案。

问题现象

当开发者在视图方法上使用 @extend_schema 注解并指定 many=True 的序列化器作为响应时，生成的 Swagger UI 文档会错误地显示分页结构，而实际 API 返回的是普通列表。例如：

@extend_schema(
    responses={
        200: MenuItemSerializer(many=True),
    }
)
@action(["get"], url_path="menu-items", detail=False)
def get_menu_items(self, request, *args, **kwargs):
    services = Service.objects.filter(property=self.request.property)
    serializer = MenuItemSerializer(services, many=True)
    return Response(serializer.data)

文档会显示类似这样的响应结构：

{
  "count": 0,
  "next": "string",
  "previous": "string",
  "results": []
}

而实际 API 返回的是：

[
    {
      "url": "string",
      "text": "string",
      "icon": "string"
    }
]

问题原因

这种现象的根本原因是 DRF-Spectacular 会检查视图的 pagination_class 属性。如果视图类全局设置了分页类，即使某个特定动作(action)没有使用分页，文档生成器仍然会认为该动作应该使用分页。

解决方案

方法一：使用 @action 的 pagination_class 参数

最直接的方式是在 @action 装饰器中明确指定 pagination_class=None：

@extend_schema(
    responses={
        200: MenuItemSerializer(many=True),
    }
)
@action(["get"], url_path="menu-items", detail=False, pagination_class=None)
def get_menu_items(self, request, *args, **kwargs):
    # 方法实现

这种方式会显式地告诉 DRF-Spectacular 这个特定动作不应该使用分页。

方法二：动态设置 pagination_class 属性

如果方法一不奏效，或者你需要更灵活的控制，可以在视图类中重写 pagination_class 属性：

@property
def pagination_class(self):
    if self.action == "list":  # 只为list动作启用分页
        return ApiPagination
    return None

这种方式通过检查当前动作名称来决定是否启用分页，适用于需要为不同动作配置不同分页行为的场景。

方法三：全局配置与局部覆盖

对于更复杂的场景，可以结合全局配置和局部覆盖：

1. 在视图类中设置默认分页类
2. 为不需要分页的动作使用 pagination_class=None
3. 为特殊动作单独指定分页类

class MyViewSet(viewsets.ModelViewSet):
    pagination_class = ApiPagination  # 默认分页
    
    @action(detail=False, pagination_class=None)
    def non_paginated_action(self, request):
        # 不分页的动作
        
    @action(detail=False, pagination_class=CustomPagination)
    def custom_paginated_action(self, request):
        # 使用自定义分页的动作

最佳实践

1. 明确意图：始终明确每个动作是否需要分页，避免依赖默认行为
2. 一致性：保持文档与实际API行为一致，避免误导API消费者
3. 测试验证：在修改分页配置后，同时测试API行为和文档生成结果
4. 注释说明：对于特殊的分页配置，添加注释说明原因

通过以上方法，开发者可以精确控制 DRF-Spectacular 生成的文档中列表响应的格式，确保文档准确反映API的实际行为。