NSwag项目中System.Text.Json序列化设置未正确应用的解决方案

背景介绍

在.NET生态系统中，NSwag是一个流行的工具，用于生成Swagger/OpenAPI文档和客户端代码。当开发者使用Minimal API（不依赖MVC框架）构建应用程序时，可能会遇到System.Text.Json序列化设置未被NSwag正确识别的问题。

问题现象

开发者在使用纯Minimal API项目时发现，虽然应用程序内部配置了camelCase的JSON序列化策略，但NSwag生成的OpenAPI/Swagger文档仍然输出PascalCase格式的属性名。这与应用程序的实际行为不符，可能导致前端客户端与后端API之间的数据格式不一致。

根本原因

NSwag默认通过MvcOptions来获取JSON序列化设置。在纯Minimal API项目中，由于没有使用MVC框架，这些设置不会被自动配置，导致NSwag无法获取到应用程序的System.Text.Json配置。

解决方案

1. 显式配置MvcOptions（传统方案）

开发者可以手动添加MvcOptions配置，确保NSwag能够获取到正确的序列化设置：

builder.Services.Configure<MvcOptions>(options =>
{
    options.OutputFormatters.Add(
        new SystemTextJsonOutputFormatter(
            System.Text.Json.JsonSerializerOptions.Default));
});

这种方法虽然有效，但引入了MVC相关的依赖，对于纯Minimal API项目来说不够优雅。

2. 配置HttpJsonOptions（推荐方案）

更现代的解决方案是直接配置Minimal API的JSON选项：

builder.Services.ConfigureHttpJsonOptions(options =>
{
    options.SerializerOptions.PropertyNamingPolicy = JsonNamingPolicy.CamelCase;
});

这种方法更符合Minimal API的设计理念，且能确保NSwag正确识别序列化设置。

3. 客户端自定义（前端解决方案）

对于生成的客户端代码，可以通过创建部分类来覆盖默认的JSON设置：

public partial class Client
{
    static partial void UpdateJsonSerializerSettings(JsonSerializerOptions settings)
    {
        settings.PropertyNamingPolicy = JsonNamingPolicy.CamelCase;
    }
}

这种方法适用于需要在前端代码中强制特定命名策略的场景。

最新进展

在NSwag的v14.0.7版本中，这个问题已得到修复。开发者可以直接使用ConfigureHttpJsonOptions来配置JSON序列化行为，而无需额外配置MvcOptions。

最佳实践建议

1. 对于新项目，建议使用最新版本的NSwag(v14.0.7或更高)
2. 优先使用ConfigureHttpJsonOptions来配置JSON序列化
3. 如果必须使用旧版本，可以采用显式配置MvcOptions的临时方案
4. 定期检查NSwag的更新日志，获取最新的功能改进和bug修复

通过理解这些解决方案，开发者可以确保NSwag生成的API文档与实际API行为保持一致，避免前后端数据格式不一致的问题。