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

在 ASP.NET Core 项目中，当使用 OpenAPI 规范来描述 API 时，开发者可能会遇到一个关于复杂类型引用的生成问题。本文将深入分析这个问题及其解决方案。

问题现象

当我们在 ASP.NET Core 项目中定义一个包含多个 List<List> 类型属性的模型时，OpenAPI 文档生成器会为第二个相同类型的属性生成一个无效的相对引用。例如，考虑以下模型定义：

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

生成的 OpenAPI 文档中，第二个属性 AddOrUpdate 的引用格式不正确，导致 Swagger UI 等工具无法正确解析。

技术背景

这个问题源于 System.Text.Json 的 GetSchemaAsJsonNode API 在处理重复类型时的行为。当遇到已经在类型层次结构中见过的类型时，它会生成相对引用来"重用"之前生成的模式。这种设计原本是为了减少文档体积，但在 OpenAPI 规范中却导致了兼容性问题。

根本原因

1. 相对引用问题：System.Text.Json 生成的相对引用格式与 OpenAPI.NET 库的 v1.6 版本不兼容，后者无法正确处理这种引用格式。

2. 类型重用机制：对于相同类型的多个属性，生成器试图重用模式定义，但引用路径处理不当。

解决方案

微软团队已经针对这个问题提供了两种解决方案：

1. 短期修复：在 ASP.NET Core 9.0.4 版本中，通过在处理流程中展开相对引用来解决这个问题。这个修复确保了生成的 OpenAPI 文档能够被标准工具正确解析。

2. 长期方案：从 .NET 10 开始，将依赖底层 Microsoft.OpenApi 库的改进来处理这类引用问题，提供更原生的支持。

临时解决方案

对于急需解决此问题的开发者，可以采用以下临时方案：

// 自定义端点处理生成的 OpenAPI 文档
app.MapGet("/openapi.json", async (HttpRequest request) =>
{
    var response = await HttpClient.GetAsync($"{request.Scheme}://{request.Host}/openapiErr.json");
    var jsonContent = await response.Content.ReadAsStringAsync();
    // 手动修复引用路径
    jsonContent = jsonContent.Replace("#/properties/delete/items", "DynamicTableDataPatch/properties/delete/items");
    return Results.Json(JsonNode.Parse(jsonContent)?.AsObject());
});

最佳实践

1. 对于生产环境，建议升级到包含修复的 ASP.NET Core 版本。

2. 在设计 API 模型时，如果可能，可以考虑为重复的复杂类型创建单独的类型定义，这不仅能避免这个问题，还能提高代码的可读性。

3. 定期检查 OpenAPI 文档生成结果，确保其符合规范并能被常用工具正确解析。

总结

这个问题展示了在 API 文档自动生成过程中类型处理和引用解析的复杂性。微软团队已经提供了明确的解决方案路径，开发者可以根据自身情况选择升级版本或应用临时解决方案。理解这类问题的本质有助于开发者更好地设计 API 模型和排查文档生成问题。