如何在Swagger仅支持OData查询参数时将ODataQueryOptions传入Mediator

要让Swagger显示$filter、$orderby等OData查询参数而非完整的ODataQueryOptions对象，同时保留原有Mediator的调用逻辑，有两种实用方案：

方案一：使用Swashbuckle.AspNetCore.OData官方兼容包 #

这是最简便的方式，利用官方提供的Swagger与OData集成工具：

1. 安装NuGet包

Install-Package Swashbuckle.AspNetCore.OData

2. 构建OData EDM模型
   创建静态方法生成实体的EDM模型，用于Swagger识别OData规则：

public static IEdmModel GetPersonEdmModel()
{
    var modelBuilder = new ODataConventionModelBuilder();
    modelBuilder.EntitySet<Person>("Persons");
    return modelBuilder.GetEdmModel();
}

3. 配置服务
   在Program.cs中同时配置OData和Swagger的集成：

// 配置OData
builder.Services.AddControllers()
    .AddOData(options =>
        options.Select().Filter().OrderBy().Expand().Count().SetMaxTop(100)
            .AddRouteComponents("odata", GetPersonEdmModel()));

// 配置Swagger并添加OData支持
builder.Services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo { Title = "Person API", Version = "v1" });
    c.AddOData(GetPersonEdmModel());
});

4. 保持原有控制器代码
   你的控制器方法无需修改，ODataQueryOptions<Person>会自动从查询字符串绑定，Swagger也会显示对应的OData查询参数而非复杂对象。

方案二：自定义Swagger操作过滤器 #

如果不想引入额外包，可以手动编写过滤器替换参数显示：

1. 创建操作过滤器

public class ODataQueryParamsFilter : IOperationFilter
{
    public void Apply(OpenApiOperation operation, OperationFilterContext context)
    {
        // 找到类型为ODataQueryOptions<Person>的参数
        var oDataParam = context.ApiDescription.ParameterDescriptions
            .FirstOrDefault(p => p.ParameterType == typeof(ODataQueryOptions<Person>));
        
        if (oDataParam != null)
        {
            // 移除Swagger中显示的复杂对象参数
            operation.Parameters.RemoveAll(p => p.Name == oDataParam.Name);
            
            // 添加常用的OData查询参数
            var oDataQueryParams = new List<OpenApiParameter>
            {
                new()
                {
                    Name = "$filter",
                    In = ParameterLocation.Query,
                    Schema = new OpenApiSchema { Type = "string" },
                    Description = "筛选条件，例如：Name eq '张三'"
                },
                new()
                {
                    Name = "$orderby",
                    In = ParameterLocation.Query,
                    Schema = new OpenApiSchema { Type = "string" },
                    Description = "排序规则，例如：Age desc"
                },
                new()
                {
                    Name = "$select",
                    In = ParameterLocation.Query,
                    Schema = new OpenApiSchema { Type = "string" },
                    Description = "指定返回字段，例如：Name,Age"
                },
                new()
                {
                    Name = "$top",
                    In = ParameterLocation.Query,
                    Schema = new OpenApiSchema { Type = "integer" },
                    Description = "返回最大条数"
                },
                new()
                {
                    Name = "$skip",
                    In = ParameterLocation.Query,
                    Schema = new OpenApiSchema { Type = "integer" },
                    Description = "跳过条数"
                }
            };
            
            operation.Parameters.AddRange(oDataQueryParams);
        }
    }
}

2. 注册过滤器
   在Program.cs的Swagger配置中添加这个过滤器：

builder.Services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo { Title = "Person API", Version = "v1" });
    c.OperationFilter<ODataQueryParamsFilter>();
});

3. 验证效果
   启动项目后，Swagger会显示你定义的$filter、$orderby等单独参数，用户输入后，ODataQueryOptions<Person>依然能正确绑定并传递给Mediator的查询命令。

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