ASP.NET Core 10 中 OpenAPI 2.0 重大变更解析

在 ASP.NET Core 10 预览版中，Microsoft.OpenAPI 库升级到 2.0 版本带来了对 OpenAPI 3.1 规范的支持，但同时也引入了一些重大变更。这些变更影响了包括 Swashbuckle.AspNetCore 在内的多个依赖库的正常使用。

核心变更内容

Microsoft.OpenAPI 2.0 版本重构了安全方案(OpenApiSecurityScheme)的实现方式。在之前的版本中，构造函数接受一个 OpenApiSecurityScheme 参数并复制其所有属性，包括引用(Reference)信息。但在新版本中，这一构造函数被移除，导致依赖此功能的代码无法正常工作。

典型问题表现

开发者在迁移到 .NET 10 预览版2时会发现，原本在 .NET 9 中正常工作的 JWT Bearer 认证配置不再有效。具体表现为：

1. AddSecurityDefinition 方法虽然可以添加安全定义
2. 但 AddSecurityRequirement 方法无法正确关联安全要求
3. 生成的 OpenAPI 文档中缺少预期的安全配置

技术背景

这一变更源于 OpenAPI 规范从 3.0 升级到 3.1 版本带来的架构调整。Microsoft.OpenAPI 2.0 实现了对 3.1 规范的支持，但这也意味着需要重构许多核心类的实现方式。

当前解决方案

目前开发者需要注意以下几点：

1. Swashbuckle.AspNetCore 8.0.0 版本尚未完全适配 .NET 10 预览版2
2. 需要等待相关依赖库更新以支持新的 OpenAPI 实现
3. 暂时不建议在生产环境中使用 .NET 10 预览版2的 OpenAPI 功能

未来展望

随着 .NET 10 正式版的临近，预计会有以下改进：

1. Microsoft.OpenAPI 将提供更完整的迁移文档
2. Swashbuckle.AspNetCore 将发布兼容版本
3. ASP.NET Core 文档将补充相关变更说明

开发者应关注官方更新，以便在稳定版本发布后顺利迁移。在此期间，建议继续使用 .NET 9 版本进行开发，或等待相关生态系统的完全适配。