Swashbuckle处理大关联Schema过慢，如何限制模型递归生成？

绝对能搞定这个问题！我之前维护过一个有上百张关联表的项目，Swagger加载慢到让人崩溃，后来用这几个方法解决了，给你详细说说：

Swashbuckle会复用你项目里的JSON序列化配置，所以直接在序列化设置里限制递归层级，就能从根源上切断无限递归的生成逻辑。

如果你的项目用的是Newtonsoft.Json（旧版ASP.NET Core常用）：

services.AddControllers()
    .AddNewtonsoftJson(options =>
    {
        // 直接忽略循环引用
        options.SerializerSettings.ReferenceLoopHandling = ReferenceLoopHandling.Ignore;
        // 限制序列化深度，比如只展示1-2层关联，按需调整
        options.SerializerSettings.MaxDepth = 2;
    });

同时在Swagger配置里确保对齐这个规则：

services.AddSwaggerGen(c =>
{
    // 其他Swagger配置...
    c.UseAllOfToExtendReferenceSchemas(); // 可选，配合递归限制让Schema展示更清晰
});

如果是新版ASP.NET Core默认的System.Text.Json：

services.AddControllers()
    .AddJsonOptions(options =>
    {
        options.JsonSerializerOptions.ReferenceHandler = ReferenceHandler.IgnoreCycles;
        options.JsonSerializerOptions.MaxDepth = 2;
    });

这个方法最省心，一次性解决所有API的递归问题，不用逐个调整模型。

如果不想全局限制，想针对特定模型或属性做精细化控制，可以写一个自定义SchemaFilter，手动排除那些会引发递归的关联属性。

比如写一个忽略导航属性的过滤器（你可以根据自己的表关联规则调整逻辑）：

public class IgnoreRecursiveNavigationFilter : ISchemaFilter
{
    public void Apply(OpenApiSchema schema, SchemaFilterContext context)
    {
        if (schema.Properties == null) return;

        // 这里可以根据属性名规则（比如所有带"Navigation"后缀的）排除，或者根据类型判断
        var recursiveProps = schema.Properties.Where(p => 
            p.Key.EndsWith("Navigation") ||
            // 或者排除和当前模型类型相同的引用属性
            p.Value.Reference?.Id == context.Type.Name
        ).ToList();

        foreach (var prop in recursiveProps)
        {
            schema.Properties.Remove(prop.Key);
        }
    }
}

然后在Swagger配置里注册这个过滤器：

services.AddSwaggerGen(c =>
{
    c.SchemaFilter<IgnoreRecursiveNavigationFilter>();
    // 其他配置...
});

如果排查后发现主要是自动生成的Example Value拖慢了加载速度，那直接禁用它就能立竿见影——毕竟Example只是辅助，核心的Model结构才是开发者需要的。

services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo { Title = "My API", Version = "v1" });

    // 用自定义OperationFilter移除所有Response里的Example
    c.OperationFilter<DisableAutoExampleFilter>();
});

public class DisableAutoExampleFilter : IOperationFilter
{
    public void Apply(OpenApiOperation operation, OperationFilterContext context)
    {
        foreach (var response in operation.Responses.Values)
        {
            foreach (var content in response.Content.Values)
            {
                // 清空自动生成的Example
                content.Example = null;
            }
        }
    }
}

这个方法见效最快，尤其是关联表极多的时候，Example的递归生成是最耗资源的环节。

从长远来看，最彻底的解决方式是为API定义专门的DTO（数据传输对象），而不是直接把EF Core的实体类暴露给Swagger。DTO可以只保留API需要的字段，完全避开不必要的关联和递归。

比如你的实体Order包含Customer，Customer又包含Orders循环引用，而你的API只需要返回订单基本信息和客户名称，那可以定义：

public class OrderDto
{
    public int Id { get; set; }
    public DateTime OrderDate { get; set; }
    public string CustomerName { get; set; }
}

这样Swagger生成的Model既简洁又没有递归问题，同时API返回的数据也更轻量化，一举两得。

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