.NET配置Swagger：如何让API返回字符串枚举类型？

在现代.NET（.NET Core/.NET 5+）与Swashbuckle环境下，完全可以实现你的需求，分两步配置即可：

1. 配置JSON序列化，让接口返回枚举字符串值 #

在Program.cs中配置控制器的JSON序列化选项，添加转换器确保接口返回枚举名称而非数值：

builder.Services.AddControllers()
    .AddJsonOptions(options =>
    {
        // 让枚举序列化为字符串
        options.JsonSerializerOptions.Converters.Add(new JsonStringEnumConverter());
    });

2. 配置Swashbuckle，让文档生成字符串枚举定义 #

同样在Program.cs中，配置Swagger生成器，将所有枚举描述为字符串类型：

builder.Services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo { Title = "你的API名称", Version = "v1" });
    
    // 让Swagger将所有枚举显示为字符串
    c.DescribeAllEnumsAsStrings();
});

效果验证 #

完成配置后，你的接口会返回"InProgress"而非1，同时Swagger生成的文档会变成你期望的格式：

{
  "OperationStatus": {
    "enum": [
      "Pending",
      "InProgress",
      "Success",
      "Error",
      "Warning"
    ],
    "type": "string"
  }
}

如果需要对特定枚举单独配置，也可以自定义ISchemaFilter实现更精细的控制，但上述全局配置已能满足大部分场景需求。

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