.Net Core 3.1中Swagger API返回枚举为字符串的问题排查

问题原因 #

.NET Core 3.1 默认使用 System.Text.Json 作为JSON序列化器，而你在实体类上标注的是Newtonsoft.Json的 [JsonConverter(typeof(StringEnumConverter))]，如果未配置项目切换到Newtonsoft.Json序列化，这个注解不会生效，导致接口返回枚举的数字值而非字符串。同时Swagger也需要适配Newtonsoft的配置才能正确识别枚举字符串。

解决步骤 #

1. 补充安装必要NuGet包 #

确保已安装 Microsoft.AspNetCore.Mvc.NewtonsoftJson（用于替换默认JSON序列化器）：

<PackageReference Include="Microsoft.AspNetCore.Mvc.NewtonsoftJson" Version="3.1.32" />

你已安装的 Swashbuckle.AspNetCore 和 Swashbuckle.AspNetCore.Newtonsoft 保留即可。

2. 配置MVC使用Newtonsoft.Json并全局启用字符串枚举转换 #

在 Startup.cs 的 ConfigureServices 方法中，修改MVC配置，指定使用Newtonsoft.Json并添加全局枚举转换器：

public void ConfigureServices(IServiceCollection services)
{
    // 配置控制器使用Newtonsoft.Json，全局处理枚举为字符串
    services.AddControllers()
        .AddNewtonsoftJson(options =>
        {
            // 添加字符串枚举转换器
            options.SerializerSettings.Converters.Add(new StringEnumConverter());
            // 保持驼峰命名规则，与你的实体类配置一致
            options.SerializerSettings.ContractResolver = new CamelCasePropertyNamesContractResolver();
        });

    // 常规Swagger配置
    services.AddSwaggerGen(c =>
    {
        c.SwaggerDoc("v1", new OpenApiInfo { Title = "你的API名称", Version = "v1" });
    });

    // 关键：让Swagger适配Newtonsoft.Json的序列化配置
    services.AddSwaggerGenNewtonsoftSupport();
}

3. 验证实体类注解（可选） #

确保实体类中使用的是Newtonsoft.Json的注解，而非System.Text.Json的：

// 确认引用的是Newtonsoft.Json的命名空间
using Newtonsoft.Json;
using Newtonsoft.Json.Converters;

[JsonObject(NamingStrategyType = typeof(CamelCaseNamingStrategy))]
public class SensorsSettings
{
    // ...其他属性
    [JsonConverter(typeof(StringEnumConverter))]
    public SensorType[] Type { get; set; }
}

完成以上配置后，重新运行项目，调用GET接口即可返回枚举的字符串形式，同时Swagger文档也会正确显示枚举的字符串值。

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