如何用drf-spectacular为DRF自定义带聚合字段的响应API Schema

要让drf-spectacular正确生成包含comments_amount和评论列表的API Schema，最规范的方式是创建顶层包裹序列化器，把聚合字段和评论列表字段整合进去，具体步骤如下：

1. 新增包裹序列化器 #

在你的序列化器文件中，添加一个专门用于返回列表响应的序列化器：

class CommentListResponseSerializer(serializers.Serializer):
    comments_amount = serializers.IntegerField(help_text=_("Total number of comments"))
    comments = CommentResponseSerializer(many=True, help_text=_("List of comments"))

这个序列化器明确定义了响应的两个核心字段：comments_amount是整数类型的聚合值，comments是CommentResponseSerializer序列化后的评论列表。

2. 更新视图的Schema配置 #

修改CommentView中@extend_schema的responses参数，替换为新的包裹序列化器：

@extend_schema(tags=["Product Cards"], summary="API для комментариев карточек продуктов")
class CommentView(APIView):
    @extend_schema(
        description="API для просмотра комментариев. Доступно всем пользователям.",
        parameters=[
            OpenApiParameter(
                name="card_id", description="ID карточки продукта", required=True, type=int, location="path"
            )
        ],
        # 替换为新的包裹序列化器
        responses=CommentListResponseSerializer,
    )
    def get(self, request, *args, **kwargs):
        card_id = kwargs["card_id"]
        comments = Comment.objects.filter(card_id=card_id)
        serializer = CommentResponseSerializer(comments, many=True)

        data = {
            "comments_amount": comments.count(),
            "comments": serializer.data
        }

        return Response(data, status=status.HTTP_200_OK)

注意：GET接口通常不需要请求体，可删除request=CommentInputSerializer避免Schema混淆。

3. 验证效果 #

启动服务后，访问drf-spectacular的文档页面（默认路径为/api/schema/或/swagger/），即可看到该接口的响应Schema正确展示comments_amount和comments列表的完整结构，与你预期的JSON格式完全匹配。

替代方案（无需新增序列化器） #

如果不想新增独立序列化器，也可以用drf-spectacular的InlineSerializer直接在视图中定义：

from drf_spectacular.utils import InlineSerializer

@extend_schema(
    # ...其他配置
    responses=InlineSerializer(
        name="CommentListResponse",
        fields={
            "comments_amount": serializers.IntegerField(),
            "comments": CommentResponseSerializer(many=True)
        }
    ),
)

不过这种方式复用性较差，更适合临时场景。

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