.NET API中如何接收字符串类型的Enum参数？

问题场景 #

我有一个使用Swagger生成文档的.NET API应用，其中一个接口接收如下DTO：

public class CreateCooperativeUserDTO
{
    [Required]
    public required string Name { get; set; }

    [Required]
    public required DateTime BirthDate { get; set; }

    [Required]
    public required DateTime AdmissionDate { get; set; }

    [Required]
    public required string BadgeName { get; set; }

    [Required]
    [JsonConverter(typeof(JsonStringEnumConverter<Race>))]
    public required Race Race { get; set; }
}

该DTO的Race属性为Enum类型，但在Swagger文档中它被展示为整数选项，我希望Swagger能将其展示为字符串形式，同时接口也能接收字符串类型的该参数，请问该如何实现？

解决方案 #

要同时实现Swagger文档显示Enum字符串和接口接收字符串参数，需要完成两部分配置：

1. 全局配置JSON序列化（确保接口解析字符串Enum） #

仅在DTO属性上加JsonConverter只能保证序列化/反序列化生效，但Swagger文档不会自动识别。建议在Program.cs中全局配置JSON字符串Enum转换，所有Enum都会统一生效：

builder.Services.AddControllers()
    .AddJsonOptions(options =>
    {
        options.JsonSerializerOptions.Converters.Add(new JsonStringEnumConverter());
    });

如果只想针对Race这个特定Enum生效，可以保留DTO上的[JsonConverter(typeof(JsonStringEnumConverter<Race>))]，再补充Swagger配置即可。

2. 配置Swagger生成器（让文档显示字符串Enum） #

项目默认已安装Swashbuckle.AspNetCore.SwaggerGen包，在Program.cs的Swagger配置中添加Enum字符串化处理：

builder.Services.AddSwaggerGen(c =>
{
    // 全局让所有Enum在Swagger文档中显示为字符串
    c.DescribeAllEnumsAsStrings();
});

如果需要更精细化控制（仅处理指定Enum），可以自定义SchemaFilter：

builder.Services.AddSwaggerGen(c =>
{
    c.SchemaFilter<EnumSchemaFilter>();
});

// 自定义过滤器，仅处理Race枚举
public class EnumSchemaFilter : ISchemaFilter
{
    public void Apply(OpenApiSchema schema, SchemaFilterContext context)
    {
        if (context.Type == typeof(Race))
        {
            schema.Type = "string";
            schema.Enum.Clear();
            foreach (var enumValue in Enum.GetValues(typeof(Race)))
            {
                schema.Enum.Add(new OpenApiString(enumValue.ToString()));
            }
        }
    }
}

验证效果 #

配置完成后重启项目，Swagger文档中Race参数会显示为对应的Enum字符串选项（比如Yellow/Black等，取决于你的Race枚举定义），同时接口可以正常接收字符串形式的参数，并自动反序列化为Race枚举类型。

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