.NET 5.0中为特定枚举禁用Swagger的枚举转字符串转换

解决方案 #

你可以通过自定义Swagger Schema过滤器实现对特定枚举的类型展示控制，步骤如下：

步骤1：自定义Schema过滤器 #

创建实现ISchemaFilter接口的类，在类内判断枚举类型，如果是需要按数值展示的枚举（比如HttpStatusCode），就直接生成数值类型的Schema，移除默认的字符串枚举选项：

using Microsoft.OpenApi.Models;
using Swashbuckle.AspNetCore.SwaggerGen;
using System.Net;

public class CustomEnumSchemaFilter : ISchemaFilter
{
    public void Apply(OpenApiSchema schema, SchemaFilterContext context)
    {
        // 单独指定HttpStatusCode枚举按数值展示
        if (context.Type == typeof(HttpStatusCode))
        {
            schema.Type = "integer";
            schema.Format = "int32";
            schema.Enum.Clear();
            return;
        }
        
        // 有其他需要按数值展示的枚举，可以继续追加判断条件
    }
}

步骤2：在Swagger配置中注册过滤器 #

修改你的AddSwaggerGen配置块，注册上述自定义过滤器：

services.AddSwaggerGen(c => {
    // 原有配置保持不变
    c.SwaggerDoc("v1", new OpenApiInfo {
        Version = "v1",
        Title = "API"
    });
    string xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
    string xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
    c.IncludeXmlComments(xmlPath);
    c.DocumentFilter<SignalRSwaggerGen.SignalRSwaggerGen>(new List<Assembly> { 
        typeof(NotificationUserHub).Assembly 
    });

    // 新增：注册自定义枚举Schema过滤器
    c.SchemaFilter<CustomEnumSchemaFilter>();
});

可选扩展：批量处理系统命名空间下的所有枚举 #

如果你需要将所有System命名空间下的系统枚举都按数值展示，不需要逐个指定，可以修改过滤器的判断逻辑：

public void Apply(OpenApiSchema schema, SchemaFilterContext context)
{
    if (context.Type.IsEnum && context.Type.Namespace.StartsWith("System."))
    {
        schema.Type = "integer";
        schema.Format = "int32";
        schema.Enum.Clear();
    }
}

轻量方案：仅修改个别属性的展示规则 #

如果只有零星几个属性需要按数值展示枚举，不需要全局配置，可以直接在属性上加特性标注：

public sealed class ErrorResponse {
    // 若使用Newtonsoft序列化加这个特性
    [Newtonsoft.Json.JsonConverter(typeof(Newtonsoft.Json.Converters.Int32Converter))]
    // 标注Swagger展示类型为数值
    [Swashbuckle.AspNetCore.Annotations.SwaggerSchemaType("integer")]
    public HttpStatusCode StatusCode { get; set; }

    public string Message { get; set; }
}

原理说明 #

全局配置的StringEnumConverter和AddSwaggerGenNewtonsoftSupport默认会把所有枚举识别为字符串类型展示，自定义Schema过滤器的优先级高于默认的枚举处理逻辑，可以覆盖指定类型的Schema生成规则，和实际的序列化行为保持一致。

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