DRF Swagger端点参数与Serializer不匹配问题求助

问题根源 #

你定义的MailSerializer继承了serializers.Serializer，但同时添加了Meta类（指定model和fields）——这是ModelSerializer的专属用法，两种写法混用会导致DRF无法正确识别你手动定义的字段，进而让Swagger UI展示的参数出现偏差。

解决方案 #

根据你的需求，有两种修正方式：

方式1：保留Serializer，移除Meta类 #

如果你需要手动定义所有字段（当前的写法），直接删除Meta类即可，因为Serializer不需要依赖模型自动生成字段：

from main.BusinessLayer.Model.Mails import Mails
from rest_framework import serializers

class MailSerializer(serializers.Serializer):
    # Mail Properties
    Subject =  serializers.CharField(max_length = 30, allow_blank = False)
    Sender = serializers.CharField(max_length = 30, allow_blank = False)
    Recipients = serializers.CharField(allow_blank = False)
    ReplyToAddress = serializers.CharField(max_length = 30)
    Importance = serializers.CharField(max_length = 30, allow_blank = False)
    ApplicationId = serializers.CharField(max_length = 30, allow_blank = False)

    # Mail Content
    Body = serializers.CharField(allow_blank = False)
    Attachments = serializers.CharField(allow_blank = False)

    # Other Parameters
    UseDefaultHeader = serializers.IntegerField(default = 0)
    UseDefaultFooter = serializers.IntegerField(default = 0)

    def create(self, validated_data):
        return Mails.objects.create(**validated_data)

方式2：改用ModelSerializer #

如果你的Mails模型字段和Serializer需要的字段完全一致，可以改用ModelSerializer，通过Meta类自动生成字段，无需手动重复定义：

from main.BusinessLayer.Model.Mails import Mails
from rest_framework import serializers

class MailSerializer(serializers.ModelSerializer):
    class Meta:
        model = Mails
        fields = '__all__'

    # 若需要覆盖模型字段的默认验证规则，可在此重新定义字段，例如：
    # Subject = serializers.CharField(max_length=30, allow_blank=False)

    def create(self, validated_data):
        return Mails.objects.create(**validated_data)

后续操作 #

1. 修正Serializer代码后，重启Django服务
2. 刷新Swagger UI页面，即可看到与Serializer定义一致的端点参数

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