能否在Swashbuckle生成的API文档中隐藏枚举值列表与名称描述？

Swashbuckle目前没有内置的直接控制枚举值列表展示的开关，之前调研的DescribeAllEnumsAsStrings配置仅能调整枚举值的序列化展示形式，无法移除自动生成的可选值列表。可以通过自定义OpenApi过滤器的方式实现目标效果，步骤如下：

核心实现逻辑 #

Swagger页面展示的枚举值列表本质来源于两个部分：

• OpenApi文档Schema中挂载的Enum可选值集合
• Swashbuckle生成参数描述时，自动拼接在自定义描述后方的['枚举值1', '枚举值2'...]格式文本

只要对生成的OpenApi文档做这两部分内容的裁剪，即可实现隐藏效果，且不会影响参数描述里的自定义跳转链接。

具体落地步骤 #

1. 编写自定义操作过滤器 #

新建实现IOperationFilter接口的过滤器类，遍历接口入参匹配带枚举值定义的参数，执行裁剪逻辑：

public class HideEnumValueListOperationFilter : IOperationFilter
{
    private readonly Regex _enumListSuffixRegex = new Regex(@"\s*\['.*?'\]\s*$", RegexOptions.Compiled);
    public void Apply(OpenApiOperation operation, OperationFilterContext context)
    {
        if (operation.Parameters == null) return;

        foreach (var parameter in operation.Parameters)
        {
            var schema = parameter.Schema;
            // 匹配携带枚举值定义的参数
            if (schema.Enum != null && schema.Enum.Any())
            {
                // 清空自动生成的枚举可选值集合
                schema.Enum.Clear();
                // 移除描述末尾自动拼接的枚举列表文本
                if (!string.IsNullOrWhiteSpace(parameter.Description))
                {
                    parameter.Description = _enumListSuffixRegex.Replace(parameter.Description, string.Empty);
                }
            }
        }
    }
}

2. 注册自定义过滤器 #

在项目的Swagger服务配置逻辑中，将自定义过滤器加入Swagger生成管线：

// Program.cs 或 Startup.cs 中的Swagger配置段
builder.Services.AddSwaggerGen(options =>
{
    // 原有Swagger文档生成配置保持不变
    // ...
    // 注册枚举值隐藏过滤器
    options.OperationFilter<HideEnumValueListOperationFilter>();
});

扩展适配 #

如果存在请求体、响应体中嵌套使用枚举类型的场景，可再编写实现ISchemaFilter接口的过滤器，对嵌套层级的Schema执行同样的Enum集合清空、描述后缀裁剪逻辑，覆盖所有位置的枚举展示。

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