如何用Swashbuckle创建Swagger示例展示属性支持多类型

针对你遇到的Dictionary<string, object>类型属性在Swagger中仅显示字符串示例的问题，可以通过自定义Swashbuckle Schema过滤器来强制修改OpenAPI Schema定义，实现展示多种类型值的示例。

方法步骤 #

1. 创建自定义SchemaFilter类 #

这个过滤器会专门处理目标属性，替换默认的示例为包含字符串、数字、布尔值的结构：

using Microsoft.OpenApi.Models;
using Swashbuckle.AspNetCore.SwaggerGen;
using System.Collections.Generic;

public class DictionaryObjectSchemaFilter : ISchemaFilter
{
    public void Apply(OpenApiSchema schema, SchemaFilterContext context)
    {
        // 仅针对RequestBody类的Properties属性（可按需调整范围）
        if (context.MemberInfo?.Name == nameof(RequestBody.Properties) && 
            context.Type == typeof(Dictionary<string, object>))
        {
            // 覆盖默认的Schema定义
            schema.Type = "object";
            schema.Properties = new Dictionary<string, OpenApiSchema>
            {
                ["additionalProp1"] = new OpenApiSchema 
                { 
                    Type = "string", 
                    Example = new OpenApiString("string") 
                },
                ["additionalProp2"] = new OpenApiSchema 
                { 
                    Type = "integer", 
                    Format = "int32", 
                    Example = new OpenApiInteger(123) 
                },
                ["additionalProp3"] = new OpenApiSchema 
                { 
                    Type = "boolean", 
                    Example = new OpenApiBoolean(true) 
                }
            };
            // 移除默认的additionalProperties设置，避免冲突
            schema.AdditionalProperties = null;
        }
    }
}

2. 注册SchemaFilter到Swagger服务 #

在Program.cs（或Startup.cs）的Swagger配置中添加这个过滤器：

builder.Services.AddSwaggerGen(c =>
{
    // 注册自定义Schema过滤器
    c.SchemaFilter<DictionaryObjectSchemaFilter>();
    
    // 你的其他Swagger配置（比如文档信息、注释路径等）
});

原理说明 #

Swashbuckle默认会将Dictionary<string, object>推断为"additionalProperties为string类型"的结构，这是框架对object类型的默认处理逻辑导致的。通过自定义SchemaFilter，我们可以直接修改生成的OpenAPI Schema，强制指定属性的类型和示例值，从而达到展示多种类型的效果。

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