如何配置Swagger/NSwag在生成OpenAPI时保留decimal数据类型

解决方法 #

根据你使用的Swagger生成组件不同，选择对应全局配置即可自动将所有decimal类型字段的format设为decimal，无需手动修改openapi文件或单个字段加注解。

如果你使用Swashbuckle.AspNetCore生成OpenAPI文档 #

在服务注册阶段添加decimal类型的全局映射即可：

builder.Services.AddSwaggerGen(options =>
{
    // 映射非可空decimal
    options.MapType<decimal>(() => new OpenApiSchema
    {
        Type = "number",
        Format = "decimal"
    });
    // 映射可空decimal
    options.MapType<decimal?>(() => new OpenApiSchema
    {
        Type = "number",
        Format = "decimal",
        Nullable = true
    });
});

如果你使用NSwag.AspNetCore生成OpenAPI文档 #

在注册OpenAPI文档服务时添加类型映射规则：

builder.Services.AddOpenApiDocument(options =>
{
    options.TypeMappers.Add(new TypeMapper(
        typeof(decimal), 
        new OpenApiSchema { Type = "number", Format = "decimal" }
    ));
    options.TypeMappers.Add(new TypeMapper(
        typeof(decimal?), 
        new OpenApiSchema { Type = "number", Format = "decimal", IsNullableRaw = true }
    ));
});

之前添加的注解无效的原因 #

你使用的[JsonSchema]注解属于NSwag或Newtonsoft.Json.Schema的专属注解，如果你用Swashbuckle生成文档，默认使用System.Text.Json序列化体系，无法识别该注解。如果需要单个字段单独配置，可安装Swashbuckle.AspNetCore.Annotations包后使用[SwaggerSchema(Format = "decimal")]注解。

配置完成后重新执行dotnet swagger命令生成openapi.json，即可看到decimal字段的format属性已正确设置，后续NSwag生成客户端代码时会自动映射为C# decimal类型。

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