.NET Framework4.5.2集成Swashbuckle生成Swagger文档遇异常求助

1. 纠正swagger.json访问路径 #

你访问的/swagger/ui/swagger.json是错误路径，Swashbuckle.NET45中，swagger文档的正确路径是http://localhost/HiddenAPIName/swagger/docs/v1，直接访问这个地址可以查看生成的JSON文档，排查是否有内容。

2. 处理StackOverflowException #

这个异常大概率是API模型循环引用或文档生成逻辑低效导致的，按以下步骤修复：

方案一：优化API筛选逻辑，替换DocumentFilter #

你当前的ExcludeControllersFilter是先生成所有API路径再移除不符合的，这种方式可能触发不必要的文档生成逻辑，改为直接筛选需要的API：
修改SwaggerConfig.cs中的EnableSwagger配置，添加SelectActions来只包含api/前缀的路由：

config.EnableSwagger(c =>
{
    c.SingleApiVersion("v1", "API");
    // 直接筛选路由以api/开头的动作，替代DocumentFilter
    c.SelectActions(apiDesc => 
        apiDesc.Route?.RouteTemplate?.StartsWith("api/", StringComparison.OrdinalIgnoreCase) == true);
    c.ResolveConflictingActions(apiDescriptions => apiDescriptions.First());
})
.EnableSwaggerUi(c => {});

然后删除ExcludeControllersFilter类，避免多余逻辑。

方案二：处理模型循环引用 #

如果API返回的模型存在循环引用（比如A类包含B类属性，B类又包含A类属性），会导致Swashbuckle生成Schema时无限递归，引发StackOverflow：

1. 添加一个SchemaFilter来移除循环引用：

public class RemoveCircularReferencesSchemaFilter : ISchemaFilter
{
    public void Apply(Schema schema, SchemaRegistry schemaRegistry, Type type)
    {
        if (schema.properties == null) return;

        // 移除指向当前类型的循环引用属性
        var circularProps = schema.properties
            .Where(p => p.Value.@ref != null && p.Value.@ref.Contains(type.Name))
            .ToList();
            
        foreach (var prop in circularProps)
        {
            schema.properties.Remove(prop.Key);
        }
    }
}

2. 在Swagger配置中注册这个Filter：

config.EnableSwagger(c =>
{
    // ...其他配置
    c.SchemaFilter<RemoveCircularReferencesSchemaFilter>();
    // 可选：使用完整类型名作为Schema ID，避免类型名冲突
    c.UseFullTypeNameInSchemaIds();
})

方案三：确认Web API路由配置 #

检查你的WebApiConfig.cs是否正确配置了api/前缀的路由，确保API端点确实以api/开头：

public static void Register(HttpConfiguration config)
{
    config.Routes.MapHttpRoute(
        name: "DefaultApi",
        routeTemplate: "api/{controller}/{id}",
        defaults: new { id = RouteParameter.Optional }
    );
    // ...其他配置
    SwaggerConfig.Register(config);
}

3. 验证修复效果 #

1. 重启API项目
2. 访问http://localhost/HiddenAPIName/swagger/docs/v1，确认能正常返回JSON文档
3. 再访问http://localhost/HiddenAPIName/swagger/ui/index，页面应该能正常加载并显示API文档

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