7.【.NET10 实战--孢子记账--产品智能化】--API 文档迁移 — Swashbuckle → OpenAPI + Scalar

在本次升级过程中，除了对运行时、语言特性和基础包进行全面更新之外，还有一个同样重要的工具需要同步升级------API 文档系统。

在 .NET 8 版本的孢子记账项目中，我们采用了业界广泛使用的第三方库 Swashbuckle.AspNetCore 来自动生成 Swagger UI 风格的 API 文档。Swashbuckle 通过解析控制器和方法上的特性（Attribute）与注释，自动生成符合 OpenAPI 规范的 JSON 描述文件，并提供一个内嵌的 Swagger UI 页面，方便开发者在浏览器中直接调试接口。这套方案在 .NET 8 时代已经非常成熟，几乎成为 ASP.NET Core 项目的标配。

然而，随着 .NET 的持续演进，微软在 .NET 9 中开始将 OpenAPI 文档生成能力作为框架的一部分内置进来，并在 .NET 10 中进一步完善。开发者无需再依赖 Swashbuckle 这类第三方库，即可通过官方提供的 Microsoft.AspNetCore.OpenApi 包获得原生、轻量的 OpenAPI 文档生成支持。原生方案与 ASP.NET Core 的路由系统、最小 API（Minimal API）以及控制器模型深度集成，维护成本更低，兼容性也更有保障。

在完成从 Swashbuckle 到原生 OpenAPI 的迁移之后，我们还将引入 Scalar 来替代原有的 Swagger UI。Scalar 是一个现代化的 API 文档 UI 框架，相比传统的 Swagger UI，它提供了更美观的界面、更流畅的交互体验，以及对 OpenAPI 3.x 规范更完整的支持。原生 OpenAPI 负责生成规范文档，Scalar 负责渲染展示，能够为开发团队提供一套既符合 .NET 10 技术方向，又在使用体验上更上一层楼的 API 文档解决方案。

一、升级前的准备工作

正式升级之前，做好梳理和规划是必不可少的步骤。在一个微服务架构的项目中，API 文档配置往往分散在多个服务里，如果没有清晰的升级清单，很容易出现遗漏或者配置不一致的问题。因此，我们需要先明确本次升级涉及哪些服务、需要变更哪些 NuGet 包依赖，以及哪些代码文件需要修改。对于 API 文档系统的迁移，整体上可以归纳为以下三个方面：

NuGet 包 ：项目中所有微服务都依赖 Swashbuckle.AspNetCore 来生成 API 文档，本次升级需要将其全部卸载，并替换为新的包：用于生成 OpenAPI 规范文档的 Microsoft.AspNetCore.OpenApi。
代码修改 ：Swashbuckle 在 Program.cs 中通常通过 AddSwaggerGen、UseSwagger 和 UseSwaggerUI 等方法进行注册和中间件配置，这些调用在迁移后均需删除。与此同时，需要补充原生 OpenAPI 的服务注册代码和 Scalar 的中间件配置，确保新的文档系统能够正常运行。
Gateway 层特殊处理 ：Gateway 层承担着聚合所有下游微服务 API 文档的职责，其升级逻辑与普通微服务有所不同，需要单独对待。具体涉及以下几项操作：
- 移除原有的 Swashbuckle.AspNetCore 和负责文档聚合的 MMLib.SwaggerForOcelot 这两个包
- 安装 Scalar.AspNetCore 包，为后续接入新的文档 UI 做准备
- 修改 Program.cs，删除 Swashbuckle 相关的服务注册和中间件配置，添加 Scalar 的对应配置
- 清理 Nacos 配置中心中与 Swashbuckle 相关的配置项，避免残留的旧配置干扰运行时行为

Tip：Gateway 层的文档聚合涉及较多架构层面的调整，新的聚合方案将在后续专门文章中详细讨论，本文暂不展开。

二、升级

在升级时，我们分两部分：升级除 Gateway 层以外的普通微服务，以及升级 Gateway 层。对于普通微服务，升级步骤相对简单，主要是卸载 Swashbuckle 包、删除相关代码、安装新的 OpenAPI 包并添加对应的服务注册和中间件配置。对于 Gateway 层，则需要额外处理文档聚合的逻辑，确保新的 Scalar UI 能够正确展示所有下游服务的 API 文档。

本次升级，我们将利用 AI Coding 的 Plan 模式，在 Plan 模式下，AI 会根据我们提供的升级清单和步骤，自动生成对应的代码修改建议。开发者可以根据 AI 的建议进行审核和调整，确保每一步修改都符合项目的实际需求和代码规范。

2.1 升级普通微服务

本次需要迁移的普通微服务共有八个，它们在 Swashbuckle 的使用方式上高度一致------都是在 Program.cs 中通过相同的三行调用完成注册和中间件配置，没有复杂的自定义扩展逻辑。这种高度同质化的改动，非常适合交给 AI 以批量方式处理。我们只需一次性将所有待升级的服务列在提示词中，AI 便会逐一对每个服务生成相应的修改计划，开发者在审核无误后统一应用即可，大幅减少了重复性的手动操作。

在使用 Plan 模式时，AI 首先会对每个微服务的项目文件（.csproj）和 Program.cs 进行分析，识别出 Swashbuckle 相关的包引用和代码调用点，然后生成一份分步骤的修改计划：先卸载旧包、再删除旧代码、最后添加新的 OpenAPI 注册代码。这种"先规划、后执行"的方式让整个升级过程更加透明可控，便于开发者在真正落地之前对计划进行审查和调整。

升级普通微服务的提示词如下：

markdown 复制代码

请将以下微服务中的 `Swashbuckle.AspNetCore` 包卸载，并删除所有与 Swashbuckle 相关的代码（如 `AddSwaggerGen`、`UseSwagger` 和 `UseSwaggerUI` 的调用）。然后，安装 `Microsoft.AspNetCore.OpenApi` 包，并添加相应的服务注册和中间件配置，以启用原生 OpenAPI 文档生成。请确保新的文档系统能够正常运行，并且 API 文档页面能够正确展示接口信息。

涉及到的微服务：
- SP.ConfigService
- SP.CurrencyService
- SP.FinanceService
- SP.IdentityService
- SP.MLService
- SP.NotificationService
- SP.ReportService
- SP.ResourceService

将上述提示词提交给 AI 后，AI 会针对每个微服务逐一生成修改计划。对于每个服务，计划所涵盖的改动内容基本一致，AI Coding 生成的 Plan 如下图。

在规划 Plan 时会如果遇到需要我们确认或者缺失的信息，AI 会直接询问我们，让我们来确认或者补充。比如在上图中，AI 询问我们希望使用哪个 UI 组件来替代原有的 Swagger UI，由于我们的这八个微服务并不是之久对外的 API，而是通过 Gateway 层对外暴露的，所以我们选择不在这些微服务中引入新的 UI 组件，直接生成原生 JSON 文档即可。类似的还有询问我们迁移后需要用 IOpenApiOperationTransformer 实现相同功能，是否保留此 SwaggerTokenRequestFilter，我们选择保留，用原生 OpenAPI 的 transformer 重新实现。这些都是 AI 在生成 Plan 时主动提出的合理问题，帮助我们更好地规划升级方案。

在审核 AI 生成的计划时，重点核查以下几个方面：确认旧的 Swashbuckle 相关调用已被完整清理，没有残留；确认新增的 AddOpenApi() 调用位于 builder.Build() 之前，MapOpenApi() 调用位于 app.Run() 之前；以及确认各服务的 .csproj 文件中包引用已正确替换，不存在新旧包并存的情况。一切确认无误后，即可让 AI 执行计划，完成代码的实际修改。

2.2 升级 Gateway 层

升级 Gateway 层的步骤与普通微服务类似，但由于 Gateway 层还涉及到文档聚合的逻辑，因此在提示词中需要额外说明需要移除 MMLib.SwaggerForOcelot 包，并安装 Scalar.AspNetCore 包。同时，在代码修改部分，需要删除 Swashbuckle 和 SwaggerForOcelot 的相关配置，添加 Scalar 的中间件配置，并清理 Nacos 配置中心中的相关配置项。升级 Gateway 层的提示词如下：

markdown 复制代码

请将 Gateway 层中的 `Swashbuckle.AspNetCore` 和 `MMLib.SwaggerForOcelot` 包卸载，并删除所有与这两个库相关的代码。然后，安装 `Scalar.AspNetCore` 包，并添加相应的中间件配置，以启用新的 API 文档 UI。请确保新的文档系统能够正常运行，并且能够正确聚合和展示所有下游微服务的 API 文档。

同样，我们利用 AI Coding 的 Plan 模式来生成升级 Gateway 层的计划。由于 Gateway 层的代码结构和配置相对复杂，涉及到文档聚合的逻辑，因此在审核 AI 生成的计划时需要特别注意以下几个方面：确认 Swashbuckle 和 SwaggerForOcelot 相关的代码已被完整清理，没有残留；确认 Scalar 的中间件配置正确添加，并且位于合适的位置。具体的 Plan 图片我就不展示了，和普通微服务的 Plan 类似，只是涉及的代码文件和修改内容更多一些。

TIP：由于 Nacos 在我们的项目中只是读取，因此我们需要手动在 Nacos 配置中心中删除与 Swashbuckle 相关的配置项，AI 无法直接操作 Nacos 配置中心，因此这部分工作需要我们在 AI 执行完代码修改后手动完成。

三、总结

本文详细介绍了在 .NET 10 升级过程中，从 Swashbuckle 到原生 OpenAPI 的迁移方案，以及引入 Scalar 替代 Swagger UI 的过程。通过利用 AI Coding 的 Plan 模式，我们能够高效地规划和执行升级步骤，确保每个微服务的 API 文档系统都能顺利过渡到新的技术栈。同时，我们也强调了在升级过程中需要特别注意的细节，尤其是在 Gateway 层的升级中，涉及到文档聚合的逻辑调整。整体来看，这次升级不仅提升了项目的技术水平，也为后续的维护和扩展打下了坚实的基础。