.NET Swagger接口文档Schema为何显示关联外键Cities表结构

Swagger的Schema由.NET集成的Swashbuckle组件基于接口出入参的类型结构递归扫描生成，默认配置下不会自动识别EF Core的导航属性并排除。
你的AddUser接口入参声明为User类型，而User实体中定义了一对多关系的导航属性public virtual ICollection<City> Cities { get; set;}，同时City实体中也存在反向导航属性public virtual User? User { get; set;}。组件在扫描User类型的所有公共属性时，会将Cities属性纳入解析范围，进一步递归解析City类型的结构，最终在Schema中展示出Cities表相关的字段，甚至可能出现双向引用导致的循环结构展示。
这个行为和你的业务逻辑无关——哪怕你新增用户时完全不会操作Cities字段，只要实体上存在公共的导航属性，默认配置下的Swagger都会将其识别为接口契约的一部分。

你可以根据项目场景选择以下任意一种方案解决：

方案1：添加JsonIgnore特性忽略导航属性（快速修复） #

给不需要参与接口序列化/反序列化的导航属性添加JsonIgnore特性，让JSON序列化器和Swagger组件直接跳过该属性，是最小改动的修复方式。
如果你使用.NET 6+默认的System.Text.Json序列化器，修改User类如下：

using System.Text.Json.Serialization;

namespace CRUDRevision.Models
{
    public partial class User
    {
        public User()
        {
            Cities = new HashSet<City>();
        }

        public int Id { get; set; }
        public string? Name { get; set; }
        public string? Email { get; set; }

        [JsonIgnore]
        public virtual ICollection<City> Cities { get; set; }
    }
}

如果项目使用Newtonsoft.Json作为序列化器，就引入Newtonsoft.Json命名空间，使用对应包下的[JsonIgnore]特性即可。同理可以给City类的User导航属性也加上该特性，避免双向引用导致的序列化循环问题。

方案2：使用DTO作为接口入参（工程化推荐方案） #

不要直接将EF Core的数据库实体作为接口的出入参，针对每个接口的业务场景定义专门的数据传输对象（DTO），只保留接口实际需要的字段，从根源上隔离数据库模型与对外接口契约。
针对新增用户的接口，你只需要Name和Email两个字段，可以单独定义请求DTO：

namespace CRUDRevision.DTOs
{
    public class AddUserRequestDto
    {
        public string? Name { get; set; }
        public string? Email { get; set; }
    }
}

再修改接口方法的入参类型为该DTO：

public async Task<IActionResult> AddUser([FromBody]AddUserRequestDto data)
{
    try {
        var user = new User
        {
            Name = data.Name,
            Email = data.Email,
        };

        await dbContext.Users.AddAsync(user);
        await dbContext.SaveChangesAsync();

        return Ok(new {message= "User has been added" });
    }
    catch(Exception ex)
    {
        return BadRequest(ex);
    }
}

这种方式可以避免数据库结构变动直接影响对外接口，也能防止敏感字段意外暴露，是正式项目的标准实践。

方案3：配置全局Schema过滤器（适合快速开发场景） #

如果是小项目不想修改实体、也不想额外定义DTO，可以通过自定义Swagger Schema过滤器，全局过滤掉EF Core的虚拟导航属性，不让其出现在生成的Schema中。
首先在Program.cs的Swagger服务配置中添加自定义过滤器：

builder.Services.AddSwaggerGen(c =>
{
    c.CustomSchemaIds(type => type.FullName);
    c.SchemaFilter<IgnoreNavigationPropertiesFilter>();
    // 其余原有Swagger配置保持不变
});

然后实现过滤器逻辑：

using Microsoft.OpenApi.Models;
using Swashbuckle.AspNetCore.SwaggerGen;
using System.Reflection;

public class IgnoreNavigationPropertiesFilter : ISchemaFilter
{
    public void Apply(OpenApiSchema schema, SchemaFilterContext context)
    {
        // 扫描当前类型的所有虚拟导航属性
        var propertiesToRemove = context.Type.GetProperties()
            .Where(prop => 
                prop.GetMethod?.IsVirtual == true 
                && (
                    // 过滤集合类型的导航属性（比如ICollection<City>）
                    (prop.PropertyType.IsGenericType && prop.PropertyType.GetGenericTypeDefinition() == typeof(ICollection<>))
                    // 过滤单个引用类型的导航属性（比如City里的User属性）
                    || (!prop.PropertyType.IsPrimitive && prop.PropertyType.Namespace != "System")
                )
            )
            .Select(prop => prop.Name)
            .ToList();

        foreach (var propName in propertiesToRemove)
        {
            schema.Properties?.Remove(propName);
        }
    }
}

注意：该方案的过滤规则需要根据你自己的实体编写规则调整，否则可能误过滤掉需要正常暴露的虚拟属性，灵活性较差，仅推荐临时开发使用。

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