- 修复 bug：在新版本中修复问题，而不冒破坏旧版本的风险。
- 逐步淘汰：在新版本中移除过时的功能，给用户足够的时间迁移。
常见的版本策略有这几种：
- URL 路径版本：
/api/v1/users，直观，最常见 - 查询参数版本：
/api/users?api-version=1.0 - 请求头版本：
X-API-Version: 1.0 - 媒体类型版本：
Accept: application/json; v=1.0（GitHub 在用这种方式）
每种方式都有适用场景，没有绝对的优劣。
在 C# 生态中，长期以来的事实标准是 Swashbuckle.AspNetCore，但它并没有内置版本管理支持，需要配合 Asp.Versioning 来实现。
终于，在 .NET 10 中，微软推出了自己的 OpenAPI 库 Microsoft.AspNetCore.OpenApi，并且 Asp.Versioning v10 也正式支持了这个库，版本管理和文档生成终于可以无缝结合了。
上手 Microsoft.AspNetCore.OpenApi 和 Asp.Versioning
要使用 Microsoft.AspNetCore.OpenApi 和 Asp.Versioning 来实现 API 版本管理，首先需要安装相关 NuGet 包：
|---|---------------------------------------------------|
| | #package: Asp.Versioning.Http 10.0.0 |
| | #package: Asp.Versioning.Mvc 10.0.0 |
| | #package: Asp.Versioning.Mvc.ApiExplorer 10.0.0 |
| | #package: Microsoft.AspNetCore.OpenApi 10.0.0 |
| | #package: Scalar.AspNetCore 2.6.0 |
安装完成后，在 Program.cs 中进行如下配置：
|---|-------------------------------------------------------------------------------|
| | services |
| | .AddApiVersioning(options => |
| | { |
| | options.DefaultApiVersion = new ApiVersion(1, 0); |
| | options.AssumeDefaultVersionWhenUnspecified = true; |
| | options.ReportApiVersions = true; |
| | options.ApiVersionReader = new UrlSegmentApiVersionReader(); |
| | }) |
| | .AddMvc() |
| | .AddApiExplorer(options => |
| | { |
| | options.GroupNameFormat = "'v'V"; |
| | options.SubstituteApiVersionInUrl = true; |
| | }); |
| | |
| | services.AddOpenApi("v1", options => |
| | { |
| | options.ShouldInclude = apiDescription => apiDescription.GroupName == "v1"; |
| | }); |
| | |
| | services.AddOpenApi("v2", options => |
| | { |
| | options.ShouldInclude = apiDescription => apiDescription.GroupName == "v2"; |
| | }); |
| | |
| | app.MapOpenApi(); |
| | app.MapScalarApiReference(options => |
| | { |
| | options |
| | .WithTitle("Users API - {documentName}") |
| | .AddDocuments(new[] { "v1", "v2" }); |
| | }); |
在上面的代码中，我们首先配置了 API 版本管理，指定了默认版本、版本读取方式等。然后，我们为每个版本配置了 OpenAPI 文档生成，确保每个版本都有独立的文档。最后，我们映射了 OpenAPI 和 Scalar API Reference 的路由。
控制器方面，我们可以使用特性来指定版本：
|---|-----------------------------------------------------------------------------------|
| | [ApiController] |
| | [Route("api/v{version:apiVersion}/[controller]")] |
| | [ApiVersion("1.0")] |
| | public class UsersController : ControllerBase |
| | { |
| | [HttpGet] |
| | [MapToApiVersion("1.0")] |
| | public IActionResult GetV1() |
| | { |
| | return Ok(new { Version = "v1", Users = new[] { "Alice", "Bob" } }); |
| | } |
| | } |
| | |
| | [ApiController] |
| | [Route("api/v{version:apiVersion}/[controller]")] |
| | [ApiVersion("2.0")] |
| | public class UsersV2Controller : ControllerBase |
| | { |
| | [HttpGet] |
| | [MapToApiVersion("2.0")] |
| | public IActionResult GetV2() |
| | { |
| | return Ok(new { Version = "v2", Users = new[] { "Alice", "Bob", "Charlie" } }); |
| | } |
| | } |
通过上述配置，我们就实现了基于 URL 路径的 API 版本管理，并且每个版本都有独立的 OpenAPI 文档。
这里还使用了一个叫 Scalar 的库来生成 API 参考文档。Scalar 是一个专注于生成 API 参考文档的库，支持多版本文档生成和定制化配置。通过 Scalar，我们可以轻松地为每个 API 版本生成漂亮的参考文档，方便开发者查阅。
上一张 Scalar 的图（和本项目无关）
