如何在Swashbuckle中优化Dictionary类型的Swagger输出？

我正在使用Swashbuckle Annotations和SchemaFilter，当Dictionary作为响应或类型属性时，Swagger生成的示例不符合实际类型（比如<string,object>类型的Dictionary被默认生成为<string,string>的示例），只能在描述字段里加说明，想通过配置additionalProperties来优化输出。

现有场景代码 #

1. Dictionary作为响应 #

[SwaggerResponse(StatusCodes.Status400BadRequest, "A dictionary containing the property validation errors", typeof(Dictionary<string, string>), contentTypes: "application/json")]

2. Dictionary作为类型属性 #

public class TypeToReturn
{
    [SwaggerSchema(Description = "Dictionary<string, object>")]
    public IDictionary<string, object> PropertyValues { get; }
}

解决方案：自定义SchemaFilter配置additionalProperties #

创建自定义DictionarySchemaFilter，通过additionalProperties指定Dictionary值类型的Schema，同时修正示例值的类型，让Swagger输出匹配真实的Dictionary类型。

实现自定义SchemaFilter #

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

public class DictionarySchemaFilter : ISchemaFilter
{
    public void Apply(OpenApiSchema schema, SchemaFilterContext context)
    {
        var type = context.Type;
        // 匹配所有泛型Dictionary/IDictionary类型
        if (type.IsGenericType && 
            (typeof(IDictionary<,>).IsAssignableFrom(type.GetGenericTypeDefinition()) || 
             typeof(Dictionary<,>).IsAssignableFrom(type.GetGenericTypeDefinition())))
        {
            // 获取Dictionary的值类型
            var valueType = type.GetGenericArguments()[1];
            
            // 配置additionalProperties为对应值类型的Schema
            schema.AdditionalProperties = context.SchemaGenerator.GenerateSchema(valueType, context.SchemaRepository);
            
            // 根据值类型设置对应示例，确保示例符合真实类型
            if (valueType == typeof(object))
            {
                schema.Example = new OpenApiObject
                {
                    ["key1"] = new OpenApiString("字符串示例"),
                    ["key2"] = new OpenApiInteger(123),
                    ["key3"] = new OpenApiBoolean(true)
                };
            }
            else if (valueType == typeof(string))
            {
                schema.Example = new OpenApiObject
                {
                    ["userName"] = new OpenApiString("用户名不能为空")
                };
            }
            // 可根据业务需求扩展其他值类型的示例配置
        }
    }
}

注册SchemaFilter #

在项目的Startup.cs或Program.cs中，将自定义Filter注册到Swagger生成器：

builder.Services.AddSwaggerGen(c =>
{
    // 其他Swagger相关配置...
    c.SchemaFilter<DictionarySchemaFilter>();
});

效果说明 #

• 对于IDictionary<string, object>类型，Swagger会自动生成包含字符串、数字、布尔值等不同类型值的示例，同时additionalProperties会指向object类型的Schema定义
• 对于Dictionary<string, string>类型，示例会显示字符串值，完全匹配实际类型
• 无需在[SwaggerSchema]或[SwaggerResponse]中额外添加冗余描述，Schema会自动反映Dictionary的真实类型结构

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