drf-spectacular中设置read_only/allow_null后嵌套序列化器名称在Swagger-UI消失

在用drf-spectacular搭配Swagger-UI生成Django Rest Framework序列化器文档时，遇到以下问题：当嵌套序列化器字段设置read_only=True或allow_null=True属性后，该嵌套序列化器的名称会从Swagger-UI的Schema视图中消失；移除这些属性或设为False后，名称又会正常显示。

代码示例 #

class MySerializerSerializer(serializers.ModelSerializer):
    # 该字段的序列化器名称不显示
    read_only_field = MyReadOnlySerializerSerializer(read_only=True)
    # 该字段的序列化器名称不显示
    null_field = MyNullSerializerSerializer(read_only=False, allow_null=True)
    # 该字段的序列化器名称正常显示
    normal_field = MyOtherSerializerSerializer(read_only=False)

Swagger-UI截图 #

问题原因 #

drf-spectacular默认会对带有read_only=True或allow_null=True的嵌套序列化器进行内联处理——直接把序列化器的字段结构展开到父Schema中，而非将其注册为独立的Schema组件并引用。这就导致Swagger-UI里不会显示嵌套序列化器的名称，只会展示字段细节。

解决方法 #

方法1：给嵌套序列化器显式指定组件名称

通过@extend_schema装饰器给嵌套序列化器指定组件名称，确保drf-spectacular将其注册为独立的Schema组件：

from drf_spectacular.utils import extend_schema

@extend_schema(component_name='MyReadOnlySerializer')
class MyReadOnlySerializerSerializer(serializers.ModelSerializer):
    # 你的序列化器字段定义
    pass

@extend_schema(component_name='MyNullSerializer')
class MyNullSerializerSerializer(serializers.ModelSerializer):
    # 你的序列化器字段定义
    pass

设置后，即使父序列化器中对应的字段带有read_only=True或allow_null=True属性，Swagger-UI也会引用这个命名组件，显示序列化器名称。

方法2：在父序列化器字段中显式引用Schema

使用extend_schema_field装饰器，手动指定字段引用的Schema组件，强制避免内联处理：

from drf_spectacular.utils import extend_schema_field, OpenApiReference

class MySerializerSerializer(serializers.ModelSerializer):
    read_only_field = extend_schema_field(
        OpenApiReference(ref='#/components/schemas/MyReadOnlySerializerSerializer')
    )(MyReadOnlySerializerSerializer(read_only=True))
    
    null_field = extend_schema_field(
        OpenApiReference(ref='#/components/schemas/MyNullSerializerSerializer')
    )(MyNullSerializerSerializer(read_only=False, allow_null=True))
    
    normal_field = MyOtherSerializerSerializer(read_only=False)

方法3：全局配置调整（不推荐）

若要全局禁用这类内联行为，可修改drf-spectacular的SCHEMA_COERCE_PATH_TO_BASENAME或COMPONENT_SPLIT_REQUEST等配置，但此方法会影响所有Schema的生成逻辑，建议优先使用前两种针对性方案。

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