Swagger：使用JsonStringEnumConverter序列化时保留枚举整数值的方法

问题原因 #

你配置了JsonStringEnumConverter让API以字符串形式序列化枚举，但Swagger生成的JSON文档中只保留了枚举的名称，未包含原始数值信息。NSwag生成客户端代码时，因无法获取原始数值，默认从0开始为枚举成员分配值，导致与API端定义不一致。

解决办法 #

方法1：修改API的Swagger配置，让文档包含枚举原始数值 #

在API的Program.cs中配置SwaggerGen时，添加自定义SchemaFilter，让Swagger文档同时保留枚举的名称和数值：

builder.Services.AddSwaggerGen(options =>
{
    // 为枚举添加数值信息到Swagger Schema
    options.SchemaFilter<EnumWithValuesSchemaFilter>();
});

// 自定义SchemaFilter实现
public class EnumWithValuesSchemaFilter : ISchemaFilter
{
    public void Apply(OpenApiSchema schema, SchemaFilterContext context)
    {
        if (!context.Type.IsEnum)
            return;

        schema.Enum.Clear();
        // 遍历枚举成员，同时添加名称和数值
        foreach (var enumValue in Enum.GetValues(context.Type))
        {
            schema.Enum.Add(new OpenApiString(Enum.GetName(context.Type, enumValue)));
            schema.Enum.Add(new OpenApiInteger((int)enumValue));
        }
        // 添加扩展属性存储纯数值列表，供NSwag识别
        schema.Extensions.Add("x-enum-values", new OpenApiArray(
            Enum.GetValues(context.Type)
                .Cast<int>()
                .Select(v => new OpenApiInteger(v))
                .ToList()
        ));
        schema.Type = "string";
    }
}

修改后重新生成Swagger JSON文档，其中的MyEnum会包含数值信息，NSwag生成客户端时就能正确使用原始枚举值。

方法2：调整NSwag生成配置，强制读取枚举原始数值 #

若不想修改API的Swagger配置，可在NSwag的配置文件（如nswag.json）中添加以下设置，让NSwag从扩展属性中读取原始值：

{
  "codeGenerators": {
    "csharp": {
      "generateEnums": true,
      "enumIntegerType": "int",
      "useEnumValues": true,
      "generateEnumMappingDescription": true,
      "enumNamesAsString": false
    }
  }
}

然后在PostBuild命令中使用该配置文件运行NSwag：

$(NSwagExe_Net80) run nswag.json

方法3：移除全局转换器，改为枚举类单独配置（可选） #

若API允许同时支持数值和字符串形式的枚举序列化，可移除全局的JsonStringEnumConverter，改为在枚举类上单独添加特性：

[JsonConverter(typeof(JsonStringEnumConverter))]
public enum MyEnum
{
    New = 1,
    Processed = 10
}

同时在SwaggerGen配置中关闭DescribeAllEnumsAsStrings，这样Swagger文档会默认输出枚举数值，NSwag生成客户端时直接使用原始值。此方法适合不需要强制以字符串形式传递枚举的场景。

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