如何在drf-spectacular生成的OpenAPI schema中覆盖类型名称？

方法1：自定义SerializerExtension（推荐） #

针对目标FooSerializer创建扩展类，精准修改其在Schema中的显示名称：

from drf_spectacular.extensions import SerializerExtension
from your_app.serializers import FooSerializer

class FooToBarSerializerExtension(SerializerExtension):
    target_class = FooSerializer
    match_subclasses = False

    def map_serializer(self, auto_schema, direction):
        # 获取原Schema结构
        schema = super().map_serializer(auto_schema, direction)
        # 修改显示标题
        schema['title'] = 'Bar'
        # 替换组件注册表中的名称
        if 'Foo' in auto_schema.registry._components.get('schemas', {}):
            auto_schema.registry._components['schemas']['Bar'] = auto_schema.registry._components['schemas'].pop('Foo')
        return schema

在项目settings.py的SPECTACULAR_SETTINGS中注册该扩展：

SPECTACULAR_SETTINGS = {
    # 其他配置项...
    'SERIALIZER_EXTENSIONS': [
        'your_app.extensions.FooToBarSerializerExtension',
    ],
}

此方法仅针对目标序列化器生效，不会影响其他组件，适合精准场景。

方法2：后处理钩子批量修改 #

若Foo嵌套层级较深，可在Schema生成完成后遍历修改所有相关引用：

def rename_foo_to_bar_hook(schema, generator, request, public):
    schemas = schema.get('components', {}).get('schemas', {})
    if 'Foo' not in schemas:
        return schema
    
    # 替换组件名称
    schemas['Bar'] = schemas.pop('Foo')
    schemas['Bar']['title'] = 'Bar'
    
    # 遍历所有组件，替换$ref中的Foo引用
    for component in schemas.values():
        # 处理直接引用
        if '$ref' in component:
            component['$ref'] = component['$ref'].replace('#/components/schemas/Foo', '#/components/schemas/Bar')
        # 处理属性中的引用
        if 'properties' in component:
            for prop in component['properties'].values():
                if '$ref' in prop:
                    prop['$ref'] = prop['$ref'].replace('#/components/schemas/Foo', '#/components/schemas/Bar')
        # 处理数组类型的引用
        if 'items' in component and '$ref' in component['items']:
            component['items']['$ref'] = component['items']['$ref'].replace('#/components/schemas/Foo', '#/components/schemas/Bar')
    return schema

在settings.py中配置后处理钩子：

SPECTACULAR_SETTINGS = {
    # 其他配置项...
    'POSTPROCESSING_HOOKS': [
        'your_app.hooks.rename_foo_to_bar_hook',
    ],
}

此方法可批量修改所有Foo的引用，但需注意避免误改同名组件。

方法3：直接在序列化器中指定引用名称 #

若FooSerializer无需保留原Schema名称，可直接在序列化器的Meta类中设置ref_name：

from rest_framework import serializers

class FooSerializer(serializers.ModelSerializer):
    class Meta:
        model = Foo
        fields = '__all__'
        ref_name = 'Bar'  # 直接指定Schema中的显示名称

此方法最简单直接，若该序列化器在所有场景下都需显示为Bar，推荐使用。

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