NSwag项目中System.Text.Json序列化设置未生效的问题解析

背景介绍

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

问题现象

开发者在使用纯Minimal API项目时发现，虽然API端点使用了camelCase风格的JSON序列化，但NSwag生成的OpenAPI文档却仍然显示PascalCase风格的属性命名。这与预期行为不符，因为开发者期望NSwag能够自动识别应用程序中配置的JSON序列化设置。

技术分析

根本原因

NSwag在生成OpenAPI文档时，默认会尝试从MvcOptions中获取JSON序列化设置。然而，在纯Minimal API项目中，由于没有使用MVC框架，这些设置不会被自动配置。这导致NSwag无法获取到应用程序中配置的System.Text.Json序列化选项，而是使用默认的PascalCase命名策略。

解决方案演变

1. 临时解决方案：开发者可以通过显式添加MvcOptions配置来解决问题：

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

2. 更优雅的解决方案：对于纯Minimal API项目，可以使用ConfigureHttpJsonOptions来配置JSON序列化选项：

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

3. 客户端生成时的解决方案：对于生成的客户端代码，可以通过创建部分类来覆盖JSON序列化设置：

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

最新进展

在NSwag 14.0.7版本中，这个问题已经得到修复。该版本包含了对System.Text.Json支持的改进，能够正确识别Minimal API项目中的JSON序列化设置。开发者可以升级到最新版本以避免这个问题。

最佳实践建议

1. 始终使用最新版本的NSwag以获得最佳兼容性
2. 对于纯Minimal API项目，优先使用ConfigureHttpJsonOptions来配置JSON序列化
3. 如果必须支持旧版本，可以使用临时解决方案作为过渡
4. 在生成客户端代码时，考虑使用部分类来定制序列化行为

总结

NSwag与System.Text.Json的集成在.NET生态系统中不断演进。随着Minimal API的普及，工具链也在逐步完善对这些新特性的支持。开发者应当了解这些技术细节，以便在遇到类似问题时能够快速定位和解决。