ASP.NET Core 6 Web API Swagger提交数据JSON转换错误排查

1. 循环引用问题 #

你的Department和Student模型存在双向导航属性（Department.Students和Student.Department），形成了循环依赖关系。当Swagger自动生成请求示例或你意外包含嵌套对象时，JSON序列化/反序列化器会陷入无限循环，导致无法正确转换对象。

2. Swagger默认示例包含无效嵌套数据 #

Swagger会根据模型结构自动生成请求体示例，其中可能包含students数组（针对Department）或department对象（针对Student），这些嵌套的导航属性会触发循环引用错误，即使你尝试删除部分内容也可能残留无效数据。

3. 序列化器未配置循环引用处理 #

ASP.NET Core 6默认使用System.Text.Json，它默认不处理循环引用。即使你添加了Newtonsoft.Json，若未正确配置替换默认序列化器，也无法解决问题。

方案一：使用DTO（数据传输对象）推荐 #

这是最规范的解决方案，通过创建与数据库实体分离的DTO类，仅暴露API所需字段，彻底避免循环引用。

步骤1：创建DTO类 #

// DepartmentCreateDto.cs
public class DepartmentCreateDto
{
    public string DepartmentName { get; set; }
    public int DepartmentCapacity { get; set; }
}

// StudentCreateDto.cs
public class StudentCreateDto
{
    public string StudentName { get; set; }
    public string StudentAge { get; set; }
    public int Department_id { get; set; }
}

步骤2：修改控制器动作 #

// Department控制器
[HttpPost]
public async Task<IActionResult> CreateDepartment([FromBody] DepartmentCreateDto dto)
{
    if (!ModelState.IsValid)
        return BadRequest(ModelState);

    var department = new Department
    {
        DepartmentName = dto.DepartmentName,
        DepartmentCapacity = dto.DepartmentCapacity
    };

    _context.Departments.Add(department);
    await _context.SaveChangesAsync();

    return CreatedAtAction(nameof(GetDepartment), new { id = department.Id }, department);
}

// Student控制器
[HttpPost]
public async Task<IActionResult> CreateStudent([FromBody] StudentCreateDto dto)
{
    if (!ModelState.IsValid)
        return BadRequest(ModelState);

    var student = new Student
    {
        StudentName = dto.StudentName,
        StudentAge = dto.StudentAge,
        Department_id = dto.Department_id
    };

    _context.Students.Add(student);
    await _context.SaveChangesAsync();

    return CreatedAtAction(nameof(GetStudent), new { id = student.id }, student);
}

步骤3：测试时使用正确的JSON #

创建Department时发送：

{
  "departmentName": "计算机科学",
  "departmentCapacity": 100
}

创建Student时发送：

{
  "studentName": "张三",
  "studentAge": "20",
  "department_id": 1
}

方案二：配置序列化器忽略循环引用 #

若你坚持直接使用实体模型，可以配置序列化器忽略循环引用。

针对System.Text.Json（默认） #

在Program.cs中修改服务配置：

builder.Services.AddControllers()
    .AddJsonOptions(options =>
    {
        // 忽略循环引用
        options.JsonSerializerOptions.ReferenceHandler = ReferenceHandler.IgnoreCycles;
        // 序列化时排除null属性（可选，优化Swagger示例）
        options.JsonSerializerOptions.DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull;
    });

针对Newtonsoft.Json #

1. 安装NuGet包：

Install-Package Microsoft.AspNetCore.Mvc.NewtonsoftJson

2. 在Program.cs中配置：

builder.Services.AddControllers()
    .AddNewtonsoftJson(options =>
    {
        options.SerializerSettings.ReferenceLoopHandling = ReferenceLoopHandling.Ignore;
        options.SerializerSettings.NullValueHandling = NullValueHandling.Ignore;
    });

方案三：手动清理Swagger请求体 #

测试时，手动删除请求体中的嵌套导航属性（如students数组或department对象），仅保留必填字段，避免触发循环引用错误。

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