带默认值的字段在drf-spectacular Schema中显示为可选的问题

问题描述 #

我有如下Django模型，其中布尔字段published默认值为False：

class PublishableModel(models.Model):
    """Fields used to determine if and when something is published."""
    published = models.BooleanField(default=False)
    publish_date = models.DateTimeField(blank=True, null=True)

使用drf-spectacular生成API Schema时，published字段被标记为可选（如published?: boolean），但实际需求是：

• 请求模型（创建Article）：published可选（依赖默认值）
• 响应模型（返回Article）：published必填（数据库必然存在该值）

已开启COMPONENT_SPLIT_REQUEST=True区分请求/响应类型，但带默认值的字段仍在两种类型中均被标记为可选，需要修正响应模型的字段必填性。

解决方案 #

方法一：自定义Serializer扩展（全局生效） #

通过drf-spectacular的序列化器扩展，针对带默认值的布尔字段，在响应Schema中强制标记为必填：

1. 创建扩展类：

from drf_spectacular.extensions import OpenApiSerializerExtension
from drf_spectacular.plumbing import build_basic_type
from rest_framework.fields import BooleanField

class DefaultBooleanResponseExtension(OpenApiSerializerExtension):
    target_class = BooleanField
    match_subclasses = True

    def map_serializer_field(self, auto_schema, direction):
        schema = build_basic_type(self.target)
        # 仅在响应方向，且字段有默认值时，设置为必填
        if direction == 'response' and self.target.default is not None:
            schema['required'] = True
        return schema

2. 在settings.py中注册扩展：

SPECTACULAR_SETTINGS = {
    'COMPONENT_SPLIT_REQUEST': True,
    'SERIALIZER_EXTENSIONS': [
        # 替换为你的扩展类路径
        'your_app.extensions.DefaultBooleanResponseExtension',
    ],
}

方法二：序列化器中显式区分请求/响应字段 #

如果仅需针对特定序列化器调整，可自定义字段类，分别设置请求和响应阶段的必填性：

from rest_framework import serializers
from drf_spectacular.utils import extend_schema_field, OpenApiTypes

class DefaultBooleanField(serializers.BooleanField):
    def __init__(self, *args, **kwargs):
        # 请求阶段：字段可选（依赖默认值）
        kwargs['required'] = False
        super().__init__(*args, **kwargs)

    @extend_schema_field(OpenApiTypes.BOOL)
    def to_representation(self, value):
        # 响应阶段：返回明确的布尔值，Schema会被标记为必填
        return super().to_representation(value)

# 在序列化器中使用该字段
class ArticleSerializer(serializers.ModelSerializer):
    published = DefaultBooleanField(default=False)

    class Meta:
        model = PublishableModel
        fields = ['published', 'publish_date']

方法三：视图中手动指定响应Schema（局部生效） #

针对个别视图，可通过extend_schema装饰器显式定义响应模型的必填字段：

from drf_spectacular.utils import extend_schema, OpenApiResponse
from rest_framework.views import APIView
from rest_framework.response import Response

class ArticleDetailView(APIView):
    @extend_schema(
        responses={
            200: OpenApiResponse(
                description="文章详情",
                schema={
                    'type': 'object',
                    'properties': {
                        'published': {'type': 'boolean'},
                        'publish_date': {'type': 'string', 'format': 'date-time', 'nullable': True}
                    },
                    'required': ['published']  # 显式标记为必填
                }
            )
        }
    )
    def get(self, request, pk):
        article = PublishableModel.objects.get(pk=pk)
        serializer = ArticleSerializer(article)
        return Response(serializer.data)

原理说明 #

drf-spectacular默认将带默认值的字段标记为可选，因为请求时客户端无需传入该值。但响应时，数据库中必然存在该字段的值（由默认值保证），因此需要通过扩展或显式配置，在响应Schema中强制将其设为必填。

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