ASP.NET Core OpenAPI 中相同类型集合属性的引用问题解析

在ASP.NET Core项目中使用OpenAPI/Swagger生成API文档时，开发人员可能会遇到一个有趣的模型定义问题。当某个模型类中包含两个相同类型的集合属性时，生成的OpenAPI规范会出现不规范的引用路径。

问题现象

考虑以下简单的模型定义：

public class TestModel
{
    public SubModel[] First { get; set; }
    public SubModel[] Second { get; set; }
}

public class SubModel
{
    public string Name { get; set; }
}

按照常规理解，OpenAPI生成器应该为这两个集合属性都生成指向SubModel的标准引用。然而实际生成的OpenAPI规范却显示：

"TestModel": {
  "type": "object",
  "properties": {
    "first": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/SubModel"
      }
    },
    "second": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/#/properties/first/items"
      }
    }
  }
}

可以看到，第二个集合属性"second"的items引用了一个非标准的路径，指向了第一个属性"first"的items定义，而不是直接引用SubModel。

技术背景

OpenAPI规范中，$ref引用应该指向组件schemas部分明确定义的模型。这种间接引用方式虽然技术上可能有效，但不符合最佳实践，可能导致以下问题：

1. 可读性降低：非标准引用路径难以理解
2. 工具兼容性问题：某些Swagger/OpenAPI工具可能无法正确处理这种引用
3. 维护困难：如果修改了第一个属性的定义，可能意外影响第二个属性

解决方案

这个问题已经在ASP.NET Core 9.0.400版本中得到修复。修复后的OpenAPI生成器会为相同类型的集合属性生成一致的、直接指向目标模型的引用：

"TestModel": {
  "type": "object",
  "properties": {
    "first": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/SubModel"
      }
    },
    "second": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/SubModel"
      }
    }
  }
}

临时解决方案

对于使用9.0.200版本的项目，如果遇到这个问题，可以考虑以下临时解决方案：

1. 使用自定义Schema过滤器手动修正引用
2. 考虑升级到包含修复的版本
3. 在代码中重构模型，避免使用相同类型的多个集合属性

最佳实践

为避免此类问题，建议开发人员：

1. 定期更新ASP.NET Core版本
2. 审查生成的OpenAPI文档
3. 对重要API考虑使用手动定义的OpenAPI文档
4. 为复杂模型编写单元测试验证生成的OpenAPI规范

这个问题虽然看起来是小问题，但它提醒我们在使用自动化工具时仍需保持警惕，定期验证生成的输出是否符合预期。