如何在Swagger中将decimal类型示例显示为0.00而非0？

我定义了如下CostDto类：

public class CostDto
{
    public int Id{ get; set; }
    public decimal? Price { get; set; }
}

但Swagger展示的示例却是：

{
    "Id": 0,
    "Price": 0
}

我希望Price的示例显示为0.00，明确这是decimal类型而非整数。尝试了以下配置但没生效：

services.AddSwaggerGen(options =>
{
    options.MapType<decimal>(() => new OpenApiSchema { Type = "number", Format = "decimal" });
    options.MapType<decimal?>(() => new OpenApiSchema { Type = "number", Format = "decimal", Nullable = true });
});

可行解决方案 #

方法1：直接用[Example]注解指定示例 #

这是最直接的方式，给Price属性添加Swashbuckle的[Example]注解：

using Swashbuckle.AspNetCore.Annotations;

public class CostDto
{
    public int Id { get; set; }
    [Example(0.00)]
    public decimal? Price { get; set; }
}

配置后Swagger会直接把0.00作为Price字段的示例值展示。

方法2：全局自定义SchemaFilter #

如果需要给所有decimal/decimal?类型统一设置示例值，可以写一个SchemaFilter：

public class DecimalSchemaFilter : ISchemaFilter
{
    public void Apply(OpenApiSchema schema, SchemaFilterContext context)
    {
        var targetTypes = new[] { typeof(decimal), typeof(decimal?) };
        if (targetTypes.Contains(context.Type))
        {
            schema.Type = "number";
            schema.Format = "decimal";
            schema.Example = new OpenApiDecimal(0.00m);
            schema.Nullable = context.Type == typeof(decimal?);
        }
    }
}

然后在Swagger配置里注册这个过滤器：

services.AddSwaggerGen(options =>
{
    options.SchemaFilter<DecimalSchemaFilter>();
});

这样所有decimal类型的字段都会自动使用0.00作为示例值，不用逐个属性配置。

方法3：通过Xml注释指定示例（需启用Xml注释） #

如果项目已经在用Xml注释，也可以通过注释里的<example>标签指定：

public class CostDto
{
    public int Id { get; set; }
    /// <summary>
    /// 价格字段
    /// </summary>
    /// <example>0.00</example>
    public decimal? Price { get; set; }
}

记得在Swagger配置中启用Xml注释支持：

services.AddSwaggerGen(options =>
{
    var xmlFileName = $"{System.Reflection.Assembly.GetExecutingAssembly().GetName().Name}.xml";
    var xmlFilePath = Path.Combine(AppContext.BaseDirectory, xmlFileName);
    options.IncludeXmlComments(xmlFilePath);
});

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