在 .NET 10 中将 API 版本管理与 OpenAPI 结合

为什么 API 版本管理很重要？

API 版本管理的核心价值就一句话：让接口可以持续演进，同时不影响老客户端。

比如你现在有一个用户接口：

v1 版本只返回 Id 和 Name，后来业务需要新增生日字段，v2 返回 BirthDate。如果你直接改原接口，老 App、老前端、第三方调用方都可能出问题。

所以我们通常会采用几种版本管理方式：

• URL Path Versioning：/api/v1/users
• Query String Versioning：/api/users?api-version=1.0
• Header Versioning：X-API-Version: 1.0
• Media Type Versioning：Accept: application/json; v=1.0

.NET 9/10 的 OpenAPI 有什么变化？

从 .NET 9 开始，ASP.NET Core 官方开始推荐使用：

它逐步取代过去很多项目默认使用的 Swashbuckle.AspNetCore 文档生成方式。

最简单的配置大概是这样：

启动后，你可以通过类似下面的地址访问 OpenAPI 文档：

看起来它天生就有 v1 的概念，但如果你真的要做多个 API 版本，光靠这个还不够。我们还需要把 API Versioning 和 OpenAPI 文档生成打通。

Asp.Versioning v10：为 .NET 10 做了更好的集成

这次重点要说的是 Asp.Versioning v10.0.0。

它正式面向 ASP.NET Core 10 和新的内置 OpenAPI 能力做了适配。虽然旧版 v8 也能通过 .NET 的 roll-forward 机制继续运行，但如果你是新项目，或者准备升级到 .NET 10，建议直接看 v10。

不同 API 风格需要的包略有区别：

Controllers 如何接入版本管理？

Controller 项目里，可以通过 [ApiVersion] 标记不同版本。

然后定义不同版本的 Controller：

默认情况下，Asp.Versioning 支持 Query String 版本管理，所以你可以这样访问：

这种方式对调试非常友好，也不需要改路由结构。

Minimal APIs 如何接入版本管理？

如果你用的是 Minimal APIs，需要使用 Asp.Versioning.Http。

核心是通过 NewVersionedApi 创建版本分组：

如果接口很多，不建议把所有版本都堆在 Program.cs 里。更舒服的方式是拆成扩展方法，例如：

这样 Program.cs 会干净很多，版本结构也更清晰。

换成 URL 或 Header 版本管理也很简单

如果你更喜欢 URL 风格，比如：

可以这样配置：

如果你想通过请求头传版本：

配置也很直接：

甚至可以同时支持 Query String 和 Header：

如果你的 API 面向内部系统，Query String 很方便；如果面向开放平台，Header 或 URL 版本会更规范一些。

重点来了：和 OpenAPI 集成

在 .NET 10 里，推荐使用 Asp.Versioning.OpenApi 来把版本管理和 OpenAPI 文档打通。

Controllers 的配置大概是这样：

Minimal APIs 则不需要 .AddMvc()：

这里有两个关键点：

1. AddOpenApi 要接在 AddApiVersioning 后面，这样用到的是 Asp.Versioning 提供的集成版本。
2. WithDocumentPerVersion() 会为每个 API 版本生成独立文档。

最终你可以访问：

这比以前每个版本手动 AddOpenApi("v1")、AddOpenApi("v2") 要舒服太多了。

SwaggerUI 和 Scalar 怎么办？

很多国内团队还是习惯用 SwaggerUI，看接口、调接口都很方便。

在新方案下，可以只使用 SwaggerUI 的 UI 包，让 OpenAPI 文档生成继续交给官方和 Asp.Versioning：

访问：/swagger

就可以在页面里切换不同 API 版本。

如果你想用更现代一点的 API 文档界面，也可以试试 Scalar：

访问：/scalar

Scalar 的界面更清爽，交互也比较现代。如果团队里有人喜欢 SwaggerUI，有人喜欢 Scalar，也完全可以两个都上：/swagger 和 /scalar 并存即可。

v10 相比 v8 到底爽在哪里？

以前在 Asp.Versioning v8 里，OpenAPI 多版本通常要这样配：

也就是说，你在接口上定义了一次版本，还要在 OpenAPI 配置里再维护一次版本。

版本少还好，版本一多就容易漏、容易错。

v10 的方式变成：

只需要定义一次 API 版本，OpenAPI 文档跟着版本自动生成。

这就是我觉得它最值得升级的地方：少写配置，少踩坑，也更符合现代 ASP.NET Core 的开发体验。

进一步：给 OpenAPI 文档加 lint 和 diff

如果你的团队对 API 质量要求比较高，还可以把 OpenAPI 文档接入 CI/CD。

比如使用：

• Spectral：检查 OpenAPI 文档是否符合团队规范
• oasdiff：对比不同版本文档，识别 breaking changes
• openapi-diff / openapi-changes：做接口变更分析

举个例子，如果有人直接改了 v1 接口的返回结构，导致老客户端可能崩掉，oasdiff 可以在 PR 阶段就发现破坏性变更。

这时候你就可以要求开发者新增 v2，而不是直接破坏 v1。

对于中大型团队来说，这一步非常有价值。它能把“API 规范”从口头约定，变成真正可执行的工程约束。