.NET 6 Minimal API如何将ProductsDto字段添加至Swagger UI？

一、解决[FromQuery]绑定Dto为空的问题 #

情况1：自定义BindAsync是必要的 #

如果必须保留自定义绑定逻辑，检查你的IBindableModelBinder实现，确保它从查询参数集合中读取值填充Dto，而非请求体或其他来源。示例实现如下：

public class ProductsDtoBinder : IBindableModelBinder
{
    public async ValueTask<BindResult> BindAsync(BindContext context)
    {
        var query = context.HttpContext.Request.Query;
        var dto = new ProductsDto();

        // 逐个映射查询参数到Dto属性
        if (int.TryParse(query["Page"], out var page))
            dto.Page = page;
        if (int.TryParse(query["PageSize"], out var pageSize))
            dto.PageSize = pageSize;
        dto.Category = query["Category"];

        return BindResult.Success(dto);
    }
}

注册绑定器后，端点中无需额外添加[FromQuery]，自定义绑定器会自动处理查询参数映射。

情况2：无特殊绑定逻辑 #

如果不需要自定义绑定逻辑，直接移除自定义BindAsync，使用Minimal API默认的[FromQuery]绑定即可：

app.MapGet("/products", ([FromQuery] ProductsDto dto) =>
{
    return Results.Ok(dto);
})
.WithOpenApi();

只要Dto属性名称与查询参数名称一致，框架会自动完成映射，不会出现空值问题。

二、让Swagger UI展示ProductsDto的所有字段 #

方式1：使用[AsParameters]特性（推荐） #

如果使用自定义绑定器，在端点参数上添加[AsParameters]特性，Swagger会自动将Dto的所有属性拆分为独立查询参数展示：

app.MapGet("/products", ([AsParameters] ProductsDto dto) =>
{
    // 业务逻辑
    return Results.Ok(dto);
})
.WithName("GetProducts")
.WithOpenApi();

方式2：自定义Swagger SchemaFilter #

如果需要更精细的控制，可通过ISchemaFilter手动配置Swagger文档，添加Dto的字段定义：

public class ProductsDtoSchemaFilter : ISchemaFilter
{
    public void Apply(OpenApiSchema schema, SchemaFilterContext context)
    {
        if (context.Type != typeof(ProductsDto)) return;

        // 添加Dto属性到Swagger Schema
        schema.Properties.Add("Page", new OpenApiSchema { Type = "integer", Format = "int32" });
        schema.Properties.Add("PageSize", new OpenApiSchema { Type = "integer", Format = "int32" });
        schema.Properties.Add("Category", new OpenApiSchema { Type = "string" });
        
        // 标记必填字段（可选）
        schema.Required = new HashSet<string> { "Page", "PageSize" };
    }
}

然后在Swagger配置中注册该Filter：

builder.Services.AddSwaggerGen(c =>
{
    c.SchemaFilter<ProductsDtoSchemaFilter>();
});

方式3：默认[FromQuery]绑定的自动识别 #

如果使用默认的[FromQuery]绑定（无自定义BindAsync），Swagger会自动识别Dto的所有属性并展示为查询参数，无需额外配置。

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