.NET Minimal API如何让枚举默认序列化为字符串并适配Swagger？

我在使用.NET Minimal API开发时，已经通过ConfigureHttpJsonOptions全局配置了JSON序列化/反序列化采用字符串而非整数处理枚举，但Swashbuckle.AspNetCore生成的Swagger文档里，枚举仍以整数形式展示，请求示例如下：

{
  "name": "string",
  "type": 0
}

实际期望的请求示例是枚举字符串形式：

{
  "name": "string",
  "type": "Arithmetic"
}

原代码示例 #

using System.Text.Json.Serialization;

var builder = WebApplication.CreateBuilder(args);

// 全局配置JSON序列化使用字符串枚举
builder.Services.ConfigureHttpJsonOptions(options =>
{
    options.SerializerOptions.Converters.Add(new JsonStringEnumConverter());
});

builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI();
}

app.UseHttpsRedirection();

app.MapPost("/api/v1/test", (TestRequest request) => Results.Ok(request));

app.Run();

public enum GridType
{
    Arithmetic,
    Geometric
}

public class TestRequest
{
    public required string Name { get; init; }
    public required GridType Type { get; set; }
}

解决方法 #

问题核心：ConfigureHttpJsonOptions仅配置了ASP.NET Core自身的JSON处理逻辑，Swagger文档生成不会自动继承这个配置，需要单独对SwaggerGen进行枚举显示配置。

方案一：内置方法快速配置

修改AddSwaggerGen的配置，添加DescribeAllEnumsAsStrings()，让所有枚举在Swagger中以字符串形式展示：

builder.Services.AddSwaggerGen(options =>
{
    // 让所有枚举在Swagger文档中显示为字符串
    options.DescribeAllEnumsAsStrings();
});

方案二：自定义SchemaFilter（灵活控制）

如果需要更精细的枚举展示控制，可以自定义SchemaFilter：

1. 实现ISchemaFilter接口：

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

public class StringEnumSchemaFilter : ISchemaFilter
{
    public void Apply(OpenApiSchema schema, SchemaFilterContext context)
    {
        if (context.Type.IsEnum)
        {
            // 将枚举类型标记为string
            schema.Type = "string";
            schema.Format = null;
            schema.Enum.Clear();
            
            // 添加所有枚举的字符串值到Swagger枚举列表
            foreach (var enumValue in Enum.GetValues(context.Type))
            {
                schema.Enum.Add(new OpenApiString(enumValue.ToString()));
            }
        }
    }
}

2. 在SwaggerGen中注册该Filter：

builder.Services.AddSwaggerGen(options =>
{
    options.SchemaFilter<StringEnumSchemaFilter>();
});

效果验证 #

修改完成后重启项目，打开Swagger UI，请求示例中的枚举会显示为字符串形式，符合预期。

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