.NET Core Web API返回数据但Swagger响应显示空对象问题

常见原因及修复步骤 #

1. 模型类属性未设置公共访问修饰符 #

如果模型类属性是private或protected，Swagger无法识别这些属性，会显示空对象。必须确保属性为public：

// 错误示例
public class ResponseModel
{
    int Id { get; set; }
    string Name { get; set; }
}

// 正确示例
public class ResponseModel
{
    public int Id { get; set; }
    public string Name { get; set; }
}

2. 数据契约或XML注释配置缺失 #

如果使用[DataContract]特性标记模型类，必须给需要暴露的属性添加[DataMember]，否则Swagger无法识别：

using System.Runtime.Serialization;

[DataContract]
public class ResponseModel
{
    [DataMember]
    public int Id { get; set; }
    
    [DataMember]
    public string Name { get; set; }
}

若启用XML注释，需确保项目生成XML文件，并在Swagger配置中引入：

// Program.cs 中的Swagger配置
builder.Services.AddSwaggerGen(c =>
{
    var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
    var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
    c.IncludeXmlComments(xmlPath);
});

同时在项目属性的「生成」选项卡中勾选「XML文档文件」。

3. 模型类为内部类（internal） #

如果模型类访问修饰符是internal，Swagger默认无法读取。要么将类改为public，要么在Swagger配置中添加内部类型支持：

builder.Services.AddSwaggerGen(c =>
{
    c.IncludeXmlComments(xmlPath);
    // 允许识别内部类型
    c.DocInclusionPredicate((docName, apiDesc) =>
    {
        var returnType = apiDesc.ActionDescriptor.ReturnType.GetGenericArguments().FirstOrDefault();
        return returnType != null && (returnType.IsPublic || returnType.IsNestedPublic);
    });
});

4. 接口返回匿名类型而非定义的模型类 #

如果接口返回的是匿名对象（如Ok(new { Id = 1, Name = "Test" })），而Swagger配置中指定了返回模型类，会出现不匹配导致空对象。需确保返回的是定义好的模型实例：

// 错误示例
[HttpGet]
public IActionResult Get()
{
    return Ok(new { Id = 1, Name = "Test" });
}

// 正确示例
[HttpGet]
public IActionResult Get()
{
    var model = new ResponseModel { Id = 1, Name = "Test" };
    return Ok(model);
}

5. 循环引用导致序列化失败 #

模型类之间存在循环引用（如A包含B，B又包含A）时，Swagger无法正常序列化。可通过[JsonIgnore]忽略循环属性，或在Json配置中处理：

builder.Services.AddControllers()
    .AddJsonOptions(options =>
    {
        options.JsonSerializerOptions.ReferenceHandler = ReferenceHandler.IgnoreCycles;
    });

6. Swagger包版本或中间件配置问题 #

检查是否使用了过时的Swashbuckle.AspNetCore包，建议更新到最新稳定版。同时确保Program.cs中正确启用Swagger中间件：

app.UseSwagger();
app.UseSwaggerUI(c =>
{
    c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
});

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