NSwag中枚举类型生成问题的解决方案

问题背景

在使用NSwag工具从C#代码生成TypeScript客户端时，许多开发者会遇到枚举类型生成不符合预期的问题。特别是在从NSwag 13.x版本升级到14.x版本后，枚举的生成方式发生了变化，导致生成的TypeScript代码不符合项目需求。

典型问题表现

在NSwag 13.x版本中，C#枚举会被正确地生成为带有名称和对应值的TypeScript枚举：

export enum ChronoUserPersonalRights {
    NoRights = 0,
    ReadWrite = 1,
    ReadOnly = 2,
}

但在升级到14.x版本后，生成的枚举变成了数字索引形式：

export enum ChronoUserPersonalRights {
    _0 = 0,
    _1 = 1,
    _2 = 2,
}

或者在某些配置下，会生成不带数值的字符串枚举：

export enum ChronoUserRightsEnum {
    Firma = "Firma",
    Department = "Department",
    Person = "Person",
}

解决方案

要解决这个问题，需要在.NET应用程序的启动配置中添加JSON序列化选项，明确指定枚举的序列化方式：

services.AddControllersWithViews().AddJsonOptions(o =>
    o.JsonSerializerOptions.Converters.Add(new JsonStringEnumConverter())
);

这个配置告诉ASP.NET Core使用字符串而非数字来序列化枚举值。但这样配置后，生成的TypeScript枚举会丢失原始的数字值，只保留字符串表示。

完整解决方案

为了同时保留枚举的名称和数值，需要进行以下完整配置：

1. 服务端配置：

在Startup.cs或Program.cs中，配置JSON序列化选项：

services.AddControllers()
    .AddJsonOptions(options =>
    {
        // 保留枚举的原始数值
        options.JsonSerializerOptions.Converters.Add(new JsonStringEnumConverter(JsonNamingPolicy.CamelCase, false));
    });

2. NSwag配置：

在nswag.json配置文件中，确保enumStyle设置为"Enum"：

"codeGenerators": {
    "openApiToTypeScriptClient": {
        "enumStyle": "Enum",
        // 其他配置...
    }
}

深入理解

这个问题的根源在于NSwag 14.x版本对OpenAPI/Swagger规范的更严格遵循。在OpenAPI规范中，枚举可以有多种表示方式：

1. 整数枚举：直接使用枚举的底层数值
2. 字符串枚举：使用枚举成员的名称
3. 描述性枚举：使用枚举成员上的Description特性

NSwag 14.x默认行为的变化反映了对规范更严格的遵循，但也带来了与之前版本的兼容性问题。通过适当的配置，开发者可以控制枚举的生成方式，使其符合项目需求。

最佳实践

1. 明确指定枚举序列化方式：在服务端明确配置枚举的序列化行为，避免依赖默认值
2. 保持前后端一致：确保TypeScript客户端生成的枚举与服务端定义保持一致
3. 考虑兼容性：在升级NSwag版本时，检查枚举生成方式的变化，必要时调整配置
4. 文档化约定：在团队中明确枚举的序列化和生成规范，避免不同开发者采用不同方式

通过以上方法，开发者可以有效地控制NSwag生成枚举类型的方式，确保生成的TypeScript代码符合项目需求。