Swashbuckle.AspNetCore 中 Swagger UI 冻结问题的分析与解决

问题现象

在使用 Swashbuckle.AspNetCore 6.6.2 版本为 ASP.NET Core 8.0 应用程序生成 Swagger 文档时，开发人员遇到了一个特殊问题：当 API 端点使用特定类型的路由参数时，Swagger UI 页面会陷入无限循环，导致浏览器冻结并持续消耗大量内存（约20GB）。

问题代码分析

问题出现在以下端点定义中：

[Route("/api/v1/products/terminate/{id}")]
[HttpPost]
public async Task<IActionResult> Terminate(
    [SwaggerParameter("Product ID", Required = true)][FromRoute] MyType<Product> id,
    [SwaggerParameter("Terminate product request", Required = false)][FromBody] TerminateProductRequest request)

其中 MyType<T> 的定义最初为：

public class MyType<TType>
{
    public Type Value => typeof(TType);  // 使用表达式体属性
}

根本原因

问题的根源在于 Swashbuckle 在生成 OpenAPI 规范时，会递归分析所有参数类型的公共成员。当遇到 Type 类型的属性时，由于 Type 类型本身包含大量元数据信息，这会导致 Swashbuckle 陷入无限递归：

1. Swashbuckle 尝试为 MyType<Product> 生成 Schema
2. 发现 Value 属性返回 Type 类型
3. 开始分析 Type 类型的所有公共成员
4. Type 类型包含大量自引用属性，导致无限循环

解决方案

方案一：修改属性定义

将表达式体属性改为字段或自动属性：

public class MyType<TType>
{
    public Type Value = typeof(TType);  // 改为字段
}

或者：

public class MyType<TType>
{
    public Type Value { get; } = typeof(TType);  // 自动属性
}

方案二：使用 JsonIgnore 特性

如果 Value 属性仅用于服务端逻辑而不需要暴露给客户端：

public class MyType<TType>
{
    [JsonIgnore]
    public Type Value => typeof(TType);  // 标记为不序列化
}

技术启示

1. OpenAPI 规范限制：OpenAPI/Swagger 规范不适合表示 .NET 的运行时类型信息，如 System.Type 这样的反射类型。

2. Swashbuckle 工作原理：Swashbuckle 会深度遍历所有公共成员来生成 Schema，设计 DTO 时应避免包含复杂或自引用的类型。

3. API 设计最佳实践：路由参数应尽量使用简单类型（如 GUID、字符串、数值等），复杂类型更适合放在请求体中。

4. 性能考量：当 Swagger UI 加载缓慢或内存激增时，应首先检查是否有类型导致了递归解析问题。

总结

这个问题展示了在使用 Swashbuckle.AspNetCore 时需要注意的一个重要方面：API 模型设计会直接影响 Swagger 文档生成的性能和稳定性。开发者在设计 API 参数类型时，不仅要考虑功能需求，还需要考虑这些类型在 OpenAPI 规范中的表示方式。对于仅用于服务端逻辑而不需要暴露给客户端的成员，使用 [JsonIgnore] 是更规范的解决方案。