如何让NSwag生成的C#控制器返回符合预期的JSON响应？

我使用NSwag通过YAML文件生成服务端C#控制器代码，接口可通过Postman正常调用，但返回的JSON中枚举字段是C#代码里的整数值，而非YAML定义的可读性字符串。

简化后的YAML定义 #

Car:
  type: object
  required:
    - id
    - color
    - type
  properties:
    id:
      type: integer
      format: int64
    color:
      type: string
      enum: [red, yellow]
    type:
      type: string
      enum: [a, b]

GetCarByIdResponse:
  type: object
  required:
    - car
  properties:
    car:
      $ref: '#/components/schemas/Car'

NSwag生成的C#控制器代码片段 #

public override async Task<ActionResult<GetCarByIdResponse>> GetCarById(long id)
{
    ...
    return Ok(new GetCarByIdResponse() { car = ...});
}

预期响应格式 #

{
  "car": {
    "id": 1,
    "color": "yellow",
    "type": "a"
  }
}

实际响应格式 #

注：2024-09-27更新：双引号问题已排除，原始响应中存在双引号，仅美观输出时未显示。

{
  "car": {
    "id": 1,
    "color": 1,
    "type": 0
  }
}

解决方法 #

• 调整NSwag生成配置：
  在NSwag的配置文件（如nswag.json）中，找到codeGeneratorSettings节点，设置enumHandling为String，确保生成的枚举类型默认以字符串形式序列化：

  "codeGeneratorSettings": {
    "enumHandling": "String",
    // 其他生成配置项...
  }
  

  如果使用命令行生成，添加参数：/enumHandling:String

• 配置ASP.NET Core JSON序列化：
  在项目的Program.cs中，为控制器添加JSON字符串枚举转换器，确保返回的JSON将枚举值序列化为字符串：

  builder.Services.AddControllers()
      .AddJsonOptions(options =>
      {
          options.JsonSerializerOptions.Converters.Add(new JsonStringEnumConverter());
      });
  

完成以上两步后，重新生成控制器代码并运行，接口返回的JSON中枚举字段就会显示为YAML定义的字符串值。

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