ASP.NET API返回Dictionary类型时Swagger UI示例显示为空的问题

问题原因 #

你当前使用的[ProducesResponseType]等属性指定的类型（如List<Door>、IEnumerable<Country>）和接口实际返回的Dictionary<int, string>不匹配，导致Swagger无法正确识别返回结构，只能显示空对象{}。

解决方法 #

1. 修正响应类型属性 #

将控制器方法上的响应类型属性替换为实际返回的Dictionary<int, string>类型，示例代码如下：

/// <summary>
/// 获取属性ID与属性描述的键值对字典
/// </summary>
/// <param name="x">测试参数</param>
/// <param name="y">示例参数</param>
/// <returns>属性ID与属性描述的键值对字典</returns>
/// <remarks>排除用户无权限访问的属性</remarks>
[Route("Test/{x}/{y}")]
[HttpGet]
[ProducesResponseType(typeof(Dictionary<int, string>), StatusCodes.Status200OK)]
public Dictionary<int, string> Test(bool x, bool y)
{
    return propertiesService.GetPropertyList(x, y);
}

2. 配置Swagger生成Dictionary的示例（可选） #

如果修正属性后仍无法显示示例，可以在Swagger的服务配置中手动映射Dictionary<int, string>的结构和示例，以Program.cs为例：

builder.Services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo { Title = "你的API名称", Version = "v1" });
    
    // 为Dictionary<int, string>定义Swagger显示的结构和示例
    c.MapType<Dictionary<int, string>>(() => new OpenApiSchema
    {
        Type = "object",
        Example = new OpenApiObject
        {
            ["1"] = new OpenApiString("属性描述1"),
            ["2"] = new OpenApiString("属性描述2")
        }
    });
});

3. 使用自定义示例提供器（可选） #

如果需要更灵活的示例生成，可以安装Swashbuckle.AspNetCore.Filters包，然后创建示例提供类：

public class DictionaryExample : IExamplesProvider<Dictionary<int, string>>
{
    public Dictionary<int, string> GetExamples()
    {
        return new Dictionary<int, string>
        {
            { 1, "属性A" },
            { 2, "属性B" }
        };
    }
}

然后在控制器方法上添加[SwaggerResponseExample(StatusCodes.Status200OK, typeof(DictionaryExample))]属性，同时在Swagger配置中启用示例支持：

builder.Services.AddSwaggerGen(c =>
{
    // 其他配置...
    c.ExampleFilters();
});

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