使用Django drf-spectacular生成Swagger文档时如何过滤Enum枚举值

除了你当前使用的全局preprocess_schema_enums钩子方案，还有3种更灵活、耦合度更低的实现方式，可按实际场景选择： #

方案1：字段层面自定义Schema（推荐，单字段过滤场景） #

无需修改全局逻辑，仅对指定字段生效，不会影响其他同枚举类型的字段使用，适合仅部分接口需要过滤枚举的场景：

1. 首先在models中定义完整的业务枚举：

from django.db import models

class CustomEnum(models.TextChoices):
    VALUE1 = "value1", "值1"
    VALUE2 = "value2", "值2"
    VALUE3 = "value3", "值3"
    VALUE4 = "value4", "值4"

2. 自定义序列化器字段，通过@extend_schema_field指定Swagger文档展示的枚举值：

from drf_spectacular.utils import extend_schema_field
from rest_framework import serializers

@extend_schema_field(serializers.ChoiceField(choices=[
    (CustomEnum.VALUE3, CustomEnum.VALUE3.label),
    (CustomEnum.VALUE4, CustomEnum.VALUE4.label)
]))
class FilteredCustomEnumField(serializers.ChoiceField):
    def __init__(self, **kwargs):
        # 业务校验仍然使用完整枚举，仅文档显示过滤后的值
        super().__init__(choices=CustomEnum.choices, **kwargs)

3. 需要过滤枚举的接口直接使用该自定义字段即可。

方案2：枚举类层面声明过滤规则（全场景过滤场景） #

适合同一个枚举所有引用位置都需要隐藏部分值的场景，无需硬编码Schema路径，维护成本更低：
直接在枚举类中添加__spectacular__魔法类，drf-spectacular生成Schema时会自动读取过滤后的选项：

class CustomEnum(models.TextChoices):
    VALUE1 = "value1", "值1"
    VALUE2 = "value2", "值2"
    VALUE3 = "value3", "值3"
    VALUE4 = "value4", "值4"

    class __spectacular__:
        @staticmethod
        def get_choices(enum_class):
            return [
                (value, label) for value, label in enum_class.choices 
                if value not in ["value1", "value2"]
            ]

方案3：按请求上下文动态过滤（权限关联场景） #

如果需要根据当前登录用户权限、请求来源等动态调整枚举展示内容，推荐使用preprocess_schema钩子，相比你当前的写法容错性更高：

def preprocess_schema(result, generator, request, public):
    # 示例：普通用户看不到内部枚举值，管理员可见全量
    if not request.user.is_superuser:
        schemas = result.get('components', {}).get('schemas', {})
        if 'CustomEnum' in schemas:
            origin_enum = schemas['CustomEnum']['enum']
            schemas['CustomEnum']['enum'] = [
                v for v in origin_enum if v not in ['value1', 'value2']
            ]
    return result

小提示：你当前的钩子写法缺少枚举存在性判断，如果生成Schema时该枚举没有被任何接口引用，会触发KeyError，建议补充判断逻辑。

选型建议 #

• 仅单个/少数接口字段需要过滤枚举：选方案1，耦合度最低
• 所有使用该枚举的场景都需要隐藏部分值：选方案2，维护成本最低
• 枚举值展示和用户权限/请求上下文关联：选方案3，灵活度最高

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