ASP.NET Core 中实现 OpenAPI 文档的蛇形命名规范

2025-05-03 03:26:25作者：裴锟轩Denise

项目地址：https://gitcode.com/gh_mirrors/aspnet/aspnetcore

在 ASP.NET Core 项目中，我们经常需要为 API 接口生成 OpenAPI 文档。一个常见的需求是将 JSON 数据格式中的属性名统一转换为蛇形命名(snake_case)风格，这在与某些前端框架或第三方服务交互时尤为重要。

配置 JSON 序列化选项

ASP.NET Core 提供了简单的方式来全局配置 JSON 序列化行为。我们可以通过 ConfigureHttpJsonOptions 方法来设置蛇形命名策略：

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

JsonNamingPolicy.SnakeCaseLower 是 .NET 内置的蛇形命名策略，它会自动将属性名转换为小写并用下划线分隔的形式，例如将 "userName" 转换为 "user_name"。

自定义蛇形命名策略

如果需要更灵活的控制，我们可以实现自定义的命名策略：

public class JsonSerializerSnakeCaseNamingPolicy : JsonNamingPolicy
{
    public override string ConvertName(string name)
    {
        // 使用正则表达式将驼峰命名转换为蛇形命名
        return Regex.Replace(name, @"(\w)([A-Z])", "$1_$2").ToLower();
    }
}

统一配置 JSON 序列化

为了保持代码整洁，我们可以将 JSON 序列化的配置提取为单独的方法：

static void ConfigureJsonSerializer(JsonSerializerOptions options)
{
    options.PropertyNamingPolicy = new JsonSerializerSnakeCaseNamingPolicy();
    options.Converters.Add(new JsonStringEnumConverter());
    options.DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull;
    options.WriteIndented = false;
    options.ReferenceHandler = ReferenceHandler.IgnoreCycles;
}

然后在服务配置中调用这个方法：

builder.Services.AddControllers()
    .AddJsonOptions(options => ConfigureJsonSerializer(options.JsonSerializerOptions));

builder.Services.ConfigureHttpJsonOptions(options => 
    ConfigureJsonSerializer(options.SerializerOptions));

注意事项

目前 Microsoft.AspNetCore.OpenApi 包不支持 Newtonsoft.Json，只能使用 System.Text.Json 进行序列化。
对于查询参数，如果需要蛇形命名，可以添加自定义的 ValueProviderFactory：

builder.Services.AddControllers(options =>
{
    options.ValueProviderFactories.Add(new SnakeCaseQueryValueProviderFactory());
});

通过以上配置，我们可以确保 API 的请求和响应数据都使用蛇形命名规范，同时生成的 OpenAPI 文档也会正确反映这一命名风格。这种统一的命名规范有助于提高 API 的可用性和一致性，特别是在多语言环境中使用时。

aspnetcore