ASP.NET Core 10.0预览版中OpenAPI文档引用问题解析

在ASP.NET Core 10.0预览版升级过程中，开发者遇到了OpenAPI文档引用功能失效的问题。这个问题主要出现在使用OpenAPI规范生成API文档时，文档内部的引用关系无法正确建立。

问题的核心在于.NET 10.0预览版中引入的新OpenAPI.NET库对引用处理机制的改变。新版本中的Reference类型（如OpenApiSchemaReference和OpenApiResponseReference）要求必须存在一个文档或工作区上下文才能建立和发现引用关系。这种设计导致在各类转换器（transformer）类型中构造引用变得困难。

具体表现为：

1. 在OpenAPI规范生成过程中，组件之间的引用关系丢失
2. 开发者需要手动处理OpenApiDocument对象才能建立正确的引用
3. 转换器上下文（如IOpenApiOperationTransformer）中缺乏必要的文档引用信息

微软团队已经意识到这个问题，并提出了相应的API改进方案。新方案计划在schema和operation上下文类型中增加Document属性，以支持这类引用解析需求。这将使开发者能够更自然地处理OpenAPI文档中的引用关系，而不需要手动维护文档对象。

这个问题虽然不会影响API的实际功能，但会显著影响生成的OpenAPI文档的质量和可用性。对于依赖OpenAPI文档进行API测试、文档生成或客户端代码生成的开发团队来说，这是一个需要注意的兼容性问题。

建议正在考虑升级到ASP.NET Core 10.0预览版的开发者：

1. 评估OpenAPI文档生成功能对项目的重要性
2. 如果必须使用此功能，可以暂时停留在.NET 9.0版本
3. 关注官方对此问题的修复进展
4. 在测试环境中充分验证OpenAPI文档生成功能

这个问题展示了框架升级过程中可能遇到的兼容性挑战，特别是在涉及复杂规范生成的场景下。开发者需要平衡新功能带来的优势与可能引入的问题，制定合理的升级策略。