ASP.Net Core OData 8查询选项未在Swagger UI显示问题咨询

问题本质 #

这是OData 8与Swagger（Swashbuckle.AspNetCore/NSwag）集成的已知问题：OData的查询参数（$filter、$select等）不会被Swagger默认生成器自动识别并添加到API文档中——哪怕你已经全局启用查询特性或在控制器方法上标记了[EnableQuery]。

原因很直接：[EnableQuery]是在请求处理阶段负责解析执行OData查询逻辑，而Swagger文档生成是在启动阶段基于控制器元数据生成，两者逻辑完全独立。默认的Swagger生成器没有内置识别OData查询参数的能力，自然不会把这些参数加入到Swagger UI的查询选项列表里。

关于“最新版本修复”的误区 #

截至OData 8.x最新稳定版，官方并没有提供原生Swagger集成来自动生成OData查询参数。你之前看到的“修复”说法，大概率是指社区解决方案的优化，而非官方内置支持。

可行解决方案 #

还是需要通过自定义操作过滤器手动将OData查询参数添加到Swagger文档中，以下是针对Swashbuckle.AspNetCore的实现示例：

1. 创建自定义操作过滤器

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

public class ODataQueryParametersFilter : IOperationFilter
{
    public void Apply(OpenApiOperation operation, OperationFilterContext context)
    {
        // 仅对标记了[EnableQuery]的方法添加参数
        if (!context.ApiDescription.ActionDescriptor.EndpointMetadata.Any(m => m is EnableQueryAttribute))
        {
            return;
        }

        operation.Parameters ??= new List<OpenApiParameter>();

        // 添加常用OData查询参数
        operation.Parameters.Add(new OpenApiParameter
        {
            Name = "$filter",
            In = ParameterLocation.Query,
            Description = "OData过滤表达式",
            Schema = new OpenApiSchema { Type = "string" },
            Required = false
        });

        operation.Parameters.Add(new OpenApiParameter
        {
            Name = "$select",
            In = ParameterLocation.Query,
            Description = "需要返回的属性列表（逗号分隔）",
            Schema = new OpenApiSchema { Type = "string" },
            Required = false
        });

        operation.Parameters.Add(new OpenApiParameter
        {
            Name = "$expand",
            In = ParameterLocation.Query,
            Description = "需要展开的导航属性列表（逗号分隔）",
            Schema = new OpenApiSchema { Type = "string" },
            Required = false
        });

        operation.Parameters.Add(new OpenApiParameter
        {
            Name = "$orderby",
            In = ParameterLocation.Query,
            Description = "排序表达式（例：'Name asc, Id desc'）",
            Schema = new OpenApiSchema { Type = "string" },
            Required = false
        });

        operation.Parameters.Add(new OpenApiParameter
        {
            Name = "$top",
            In = ParameterLocation.Query,
            Description = "返回的最大记录数",
            Schema = new OpenApiSchema { Type = "integer", Format = "int32" },
            Required = false
        });

        operation.Parameters.Add(new OpenApiParameter
        {
            Name = "$skip",
            In = ParameterLocation.Query,
            Description = "需要跳过的记录数",
            Schema = new OpenApiSchema { Type = "integer", Format = "int32" },
            Required = false
        });

        operation.Parameters.Add(new OpenApiParameter
        {
            Name = "$count",
            In = ParameterLocation.Query,
            Description = "是否返回匹配记录的总数",
            Schema = new OpenApiSchema { Type = "boolean" },
            Required = false
        });
    }
}

2. 注册过滤器到Swagger

在Program.cs的Swagger配置中添加该过滤器：

builder.Services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo { Title = "MyODataAPI", Version = "v1" });
    // 注册自定义OData查询参数过滤器
    c.OperationFilter<ODataQueryParametersFilter>();
});

进阶优化（可选） #

如果需要更精准的参数定义（比如限制$select只能使用实体的合法属性），可以扩展这个过滤器，通过context.ApiDescription.ActionDescriptor获取对应的EDM实体类型，生成基于实体属性的参数描述。不过对于大多数场景，上面的通用参数添加已经能满足Swagger UI的使用需求。

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