如何在drf-yasg Swagger文档中添加带自定义参数的序列化器响应示例？

错误原因 #

你遇到的报错是因为在examples配置中直接传入了UserSerializer类对象，drf-yasg无法将序列化器类直接转换为JSON格式的示例内容。

解决方案 #

有两种常用的实现方式，优先推荐第一种，可维护性更高：

方案1：自定义响应序列化器（推荐） #

先定义专门的登录接口响应序列化器，直接传给openapi.Response的schema参数即可，drf-yasg会自动根据序列化器生成文档和示例：

from rest_framework import serializers, status
from drf_yasg import openapi
from drf_yasg.utils import swagger_auto_schema

from authprofile.serializers import UserSerializer

# 自定义登录接口响应序列化器
class LoginResponseSerializer(serializers.Serializer):
    user = UserSerializer(help_text="用户信息")
    token = serializers.CharField(help_text="用户认证令牌")

login_response_schema = {
    # 登录接口通常返回200状态码，你也可以保留原来的201_CREATED按需调整
    status.HTTP_200_OK: openapi.Response(
        description="登录成功",
        schema=LoginResponseSerializer
    )
}

class LoginAPI(generics.GenericAPIView):
    serializer_class = LoginSerializer

    @swagger_auto_schema(
        operation_description="使用邮箱和密码登录",
        responses=login_response_schema
    )
    def post(self, request):
        # 原有业务逻辑不变
        serializer = self.get_serializer(data=request.data)
        serializer.is_valid(raise_exception=True)
        user = serializer.validated_data
        _, token = AuthToken.objects.create(user)
        return Response({
            "user": UserSerializer(user, context=self.get_serializer_context()).data,
            "token": token
        })

方案2：手动写静态示例 #

如果你只需要自定义显示的示例内容，不需要自动同步序列化器变更，可以直接把examples里的UserSerializer替换为实际的示例结构：

login_response_schema = {
    status.HTTP_200_OK: openapi.Response(
        description="登录成功",
        examples= {
            "application/json":{
                "user": {
                    "id": 1,
                    "email": "test@example.com",
                    "username": "测试用户"
                    # 按照你实际UserSerializer的字段补充示例即可
                },
                "token": "2c36a42f9d0e18b7c5a3f1e7d9c2b4a6f8e0d3c5",
            }
        }
    )
}

两种方案都可以解决报错问题，同时让token和用户信息的字段正常显示在Swagger文档中。

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