.NET Core下Swagger未正确返回OData响应元数据格式问题

配置不生效是三个实际问题导致的：

• 自定义响应包装类使用了Newtonsoft.Json的[JsonProperty]特性，但.NET Core 3.0+版本默认的Swashbuckle组件是基于System.Text.Json做序列化规则识别的，根本读不到你写的属性别名；而且你定义的泛型类ODataValueWithCount<T>中，Value属性直接写死为List<Project>类型，完全没有用到泛型参数T，泛型定义没有实际作用。
• 你引入的ODataOperationFilter默认会自动解析OData接口返回的IQueryable类型，生成PascalCase命名的响应结构，直接覆盖了你通过[ProducesResponseType]手动声明的响应类型。
• 自定义包装类设置为internal访问级别，部分场景下Swagger生成器和序列化框架无法通过反射正确读取类的属性配置。

1. 重写正确的响应包装类 #

将类访问级别改为public，使用对应序列化框架的属性别名特性，Value属性使用泛型参数，将非必返字段设为可空类型：
如果你的项目使用默认的System.Text.Json序列化：

using System.Text.Json.Serialization;

public class ODataPagedResponse<T>
{
    [JsonPropertyName("@odata.context")]
    public string? ODataContext { get; set; }

    [JsonPropertyName("@odata.count")]
    public int? ODataCount { get; set; }

    [JsonPropertyName("@odata.nextLink")]
    public string? ODataNextLink { get; set; }

    [JsonPropertyName("value")]
    public T? Value { get; set; }
}

如果你的项目全局配置了Newtonsoft.Json作为序列化器，把所有[JsonPropertyName]替换为[JsonProperty]即可。

2. 修正接口的响应类型声明 #

替换原有[ProducesResponseType]的类型参数，匹配新的泛型响应类：

[EnableQuery(PageSize = ITEMS_PER_PAGE)]
[ProducesResponseType(typeof(ODataPagedResponse<IEnumerable<Project>>), StatusCodes.Status200OK)]
public IQueryable<Project> GetAsync()
{
    return _projectRepository.GetProjects();
}

3. 调整Swagger生成配置 #

在AddSwaggerGen配置块中加入自定义SchemaId规则，避免OData过滤器覆盖你手动声明的响应结构：

services.AddSwaggerGen(swagger =>
{
    // 加入此行，避免不同程序集同名类型导致的Schema覆盖问题
    swagger.CustomSchemaIds(type => type.FullName);
    swagger.OperationFilter<ODataOperationFilter>();
    
    // 以下是你原有配置，保持不变即可
    swagger.SwaggerDoc("v1", new OpenApiInfo { Title = "API", Version = "0.0.1" });
    swagger.AddSecurityDefinition("Bearer", new OpenApiSecurityScheme
    {
        In = ParameterLocation.Header,
        Description = "Please insert JWT with Bearer into field",
        Name = "Authorization",
        Type = SecuritySchemeType.ApiKey
    });
    swagger.AddSecurityRequirement(new OpenApiSecurityRequirement 
    {
        {
            new OpenApiSecurityScheme
            {
                Reference = new OpenApiReference
                    {
                        Type = ReferenceType.SecurityScheme,
                        Id = "Bearer"
                    }
            },
        Array.Empty<string>()
        }
    });
    swagger.ResolveConflictingActions(apiDescription => apiDescription.First());
});

如果调整后仍然显示旧结构，直接打开你使用的ODataOperationFilter源码，注释掉其中针对IQueryable返回类型自动生成响应Schema的逻辑——你已经手动给所有OData接口声明了响应类型，不需要过滤器自动生成。

4. 验证效果 #

重启应用后清空浏览器缓存刷新Swagger页面，就能看到响应结构已经变为符合OData规范的格式：字段名带@odata.前缀、集合字段为小写value，和你预期的结构完全一致，前端可以直接基于这个结构定义TS类型。

注意：如果部分OData接口不需要返回count、nextLink字段，只需要在对应接口的[ProducesResponseType]中声明不带这些字段的响应类型即可，不需要强制所有接口复用同一个包装类。

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