如何通过NSwag在Swagger UI中正确展示Dictionary<string, string>

方法一：替换参数类型为List<KeyValuePair<string, string>> #

这是最直接的方案，无需修改NSwag配置：

1. 将方法中的IDictionary<string,string>参数替换为List<KeyValuePair<string,string>>
2. 在方法内部将列表转换为Dictionary使用

示例代码：

[HttpPost]
[Route("/api/students/{id:guid}")]
public async Task<IActionResult> ExecuteSparqlAsync(Guid Id, [FromQuery] List<KeyValuePair<string,string>> queries)
{
    var queryDictionary = queries.ToDictionary(kv => kv.Key, kv => kv.Value);
    // 后续业务逻辑使用queryDictionary
    return Ok();
}

这样Swagger UI会自动生成可动态添加的键值对输入控件，和你用List时的展示效果一致，同时ASP.NET Core能正确解析Query参数。

方法二：全局配置NSwag映射Dictionary类型 #

如果你不想修改参数类型，可以通过NSwag的全局配置将IDictionary<string,string>映射为键值对数组的Schema：
在.NET 6+的Program.cs中配置OpenApi文档：

builder.Services.AddOpenApiDocument(settings =>
{
    // 配置Schema为OpenApi3类型
    settings.SchemaSettings.SchemaType = SchemaType.OpenApi3;

    // 自定义Dictionary<string,string>的Schema生成规则
    settings.SchemaSettings.MapType<IDictionary<string, string>>(() => new OpenApiSchema
    {
        Type = "array",
        Items = new OpenApiSchema
        {
            Type = "object",
            Properties =
            {
                ["key"] = new OpenApiSchema { Type = "string" },
                ["value"] = new OpenApiSchema { Type = "string" }
            },
            Required = { "key", "value" }
        }
    });
});

配置完成后，所有IDictionary<string,string>类型的参数都会在Swagger UI中显示为可输入的键值对控件。

方法三：单个参数的Schema自定义 #

如果只想针对某个参数修改展示效果，可以给参数添加[SwaggerSchema]属性手动指定Schema：

[HttpPost]
[Route("/api/students/{id:guid}")]
public async Task<IActionResult> ExecuteSparqlAsync(Guid Id, 
    [FromQuery] 
    [SwaggerSchema(
        Type = "array",
        Items = new OpenApiSchema
        {
            Type = "object",
            Properties =
            {
                ["key"] = new OpenApiSchema { Type = "string" },
                ["value"] = new OpenApiSchema { Type = "string" }
            },
            Required = { "key", "value" }
        }
    )]
    IDictionary<string,string> queries)
{
    return Ok();
}

内容的提问来源于stack exchange，提问作者Md. Mustafizur Rahman