Django drf-spectacular使用serializer的depth参数时嵌套字段识别错误问题

DRF的depth参数实现嵌套序列化时，会动态生成匿名嵌套序列化器，所有动态生成的嵌套类统一命名为NestedSerializer。drf-spectacular解析schema时无法区分不同关联模型对应的嵌套序列化器，会复用第一个识别到的嵌套结构给所有关联字段，最终出现所有关联字段结构相同的问题，同时触发重名警告。

方案1：升级依赖版本（推荐，无业务代码侵入） #

drf-spectacular 0.21.0及以上版本已经针对DRF动态嵌套序列化器的重名问题做了官方适配，会自动根据关联模型名称为嵌套组件生成唯一标识，避免冲突。
操作步骤：

• 升级drf-spectacular到最新稳定版：pip install -U drf-spectacular
• 可同步升级djangorestframework到3.13.x及以上兼容版本，升级前做好业务兼容性测试。
  升级完成后无需修改原有序列化器代码，即可生成正确的schema示例。

方案2：自定义动态嵌套序列化器命名逻辑 #

如果受环境限制无法升级依赖，可以重写ModelSerializer的嵌套序列化器构建方法，给动态生成的嵌套类加上关联模型名称作为唯一标识：

from rest_framework.serializers import ModelSerializer

class BaseModelSerializer(ModelSerializer):
    def build_nested_field(self, field_name, relation_info, nested_depth):
        nested_cls, nested_kwargs = super().build_nested_field(field_name, relation_info, nested_depth)
        # 重命名动态序列化器，添加关联模型名避免重名
        nested_cls.__name__ = f"{relation_info.related_model._meta.object_name}NestedSerializer"
        return nested_cls, nested_kwargs

# 所有需要使用depth参数的序列化器统一继承该基类即可
class OrderSerializer(BaseModelSerializer):
    class Meta:
        model = Order
        fields = '__all__'
        depth = 1

方案3：通过drf-spectacular扩展手动指定schema #

如果只需要修复单个接口的文档示例，无需全局调整，可以用extend_schema_serializer手动指定序列化器的示例结构：

from drf_spectacular.utils import extend_schema_serializer, OpenApiExample

@extend_schema_serializer(
    examples=[
        OpenApiExample(
            "订单返回示例",
            value={
                "id": 1,
                "user": {
                    "id": 1,
                    "username": "test_user",
                    "title": "工程师"
                },
                "type": {
                    "id": 1,
                    "number": 1001
                }
            }
        )
    ]
)
class OrderSerializer(serializers.ModelSerializer):
    class Meta:
        model = Order
        fields = '__all__'
        depth = 1

虽然上述方案可以解决depth参数的schema生成问题，但如果业务中需要灵活控制嵌套字段的输出范围、校验逻辑，还是更推荐手动为关联字段指定对应的序列化器，可控性更高，也能避免各类动态序列化带来的兼容问题。

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