ASP.NET Core OpenAPI 中 List<List<string>> 类型引用的生成问题解析

在 ASP.NET Core 项目中，当使用 OpenAPI/Swagger 生成 API 文档时，开发人员可能会遇到一个关于复杂类型引用的生成问题。这个问题特别出现在当一个类中包含多个相同复杂类型的属性时，比如两个 List<List> 类型的属性。

问题现象

当定义一个包含两个 List<List> 类型属性的类时，例如：

public record DynamicTableDataPatch()
{
    public List<List<string>> Delete { get; set; } = [];
    public List<List<string>> AddOrUpdate { get; set; } = [];
}

生成的 OpenAPI 文档中会出现不正确的引用格式。具体表现为第二个属性 AddOrUpdate 的 schema 引用会生成一个相对路径 #/components/schemas/#/properties/delete/items，而不是正确的绝对路径或直接的类型定义。

技术背景

这个问题源于 ASP.NET Core 中 OpenAPI 文档生成的底层机制：

1. 系统使用 System.Text.Json 的 GetSchemaAsJsonNode API 来生成类型定义
2. 当遇到重复的类型时，STJ 会尝试重用之前生成的 schema，通过相对引用来优化文档大小
3. 当前版本的 OpenAPI.NET 库 (v1.6) 对相对引用的处理不够完善

影响范围

这个问题会影响：

1. 使用 Swagger UI 或 Scalar 等 API 文档工具的用户体验
2. 自动生成的客户端代码
3. API 文档的可读性和正确性

解决方案

微软团队已经针对这个问题提供了修复方案：

1. 对于 .NET 9.0.x 版本，修复将通过服务更新 (9.0.4) 提供
2. 修复的核心思路是在将 schema 传递给 OpenAPI.NET 之前，将所有相对引用转换为绝对引用
3. 从 .NET 10 开始，将依赖 OpenAPI.NET 库本身的改进来彻底解决这个问题

临时解决方案

在官方修复发布前，开发者可以采用以下临时解决方案：

1. 手动修改生成的 OpenAPI 文档，将相对引用替换为绝对路径
2. 使用中间件拦截 OpenAPI 文档请求，动态修正引用路径
3. 考虑将复杂类型封装为单独的类型定义

最佳实践

为避免类似问题，建议：

1. 对于重复使用的复杂类型，考虑定义明确的 DTO 类
2. 定期更新 ASP.NET Core 和相关的 OpenAPI 工具包
3. 在 CI/CD 流程中加入 OpenAPI 文档的验证步骤

这个问题展示了在 API 文档自动生成过程中类型系统处理的复杂性，也提醒我们在设计 API 时需要考虑到文档生成工具的局限性。随着 .NET 生态系统的持续改进，这类问题将得到更好的解决。