如何修改DRF接口在Swagger文档中展示的必填请求字段

Swagger接口文档是根据视图绑定的序列化器自动生成请求参数字段的。你当前直接重写post方法修改请求参数的逻辑，没有替换TokenObtainPairView默认绑定的序列化器——自带序列化器明确定义了必填字段为username和password，所以文档会一直显示这两个字段，和你实际接口支持的参数不匹配。
另外你当前修改request.POST._mutable属性的写法不符合DRF规范，还缺少邮箱不存在的异常处理，用户传未注册邮箱时会直接返回500错误。

• 第一步：自定义邮箱登录专用序列化器，继承JWT自带的TokenObtainPairSerializer，将入参字段替换为email和password，把“通过邮箱查用户名”的逻辑移到序列化器校验方法中，同时补全异常处理：

from rest_framework_simplejwt.serializers import TokenObtainPairSerializer
from django.contrib.auth import get_user_model
from rest_framework import serializers

User = get_user_model()

class EmailLoginSerializer(TokenObtainPairSerializer):
    # 移除默认的username字段
    username = None
    # 新增email必填字段
    email = serializers.EmailField(required=True, help_text="登录邮箱")
    password = serializers.CharField(required=True, write_only=True, help_text="登录密码")

    def validate(self, attrs):
        try:
            user = User.objects.get(email=attrs["email"])
        except User.DoesNotExist:
            raise serializers.ValidationError("邮箱或密码错误")
        # 把查到的用户名传给父类校验逻辑，不需要修改request对象
        attrs["username"] = user.username
        return super().validate(attrs)

• 第二步：修改登录视图，将默认序列化器替换为上面自定义的类，之前重写的post方法可以直接删除，相关逻辑已经在序列化器中实现：

from rest_framework_simplejwt.views import TokenObtainPairView
from .serializers import EmailLoginSerializer

class LoginAPIView(TokenObtainPairView):
    serializer_class = EmailLoginSerializer

修改完成后重启服务，Swagger会自动读取新序列化器的字段定义，接口文档里就会正确显示必填参数为email和password，同时接口的异常处理也符合REST规范，不会出现无意义的500报错。

不管你用drf-yasg还是drf-spectacular生成Swagger文档，只要视图正确关联了自定义序列化器，都能自动识别字段，不需要额外加装饰器做字段声明。

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