修复 bug在新版本中修复问题而不冒破坏旧版本的风险。逐步淘汰在新版本中移除过时的功能给用户足够的时间迁移。常见的版本策略有这几种URL 路径版本/api/v1/users直观最常见查询参数版本/api/users?api-version1.0请求头版本X-API-Version: 1.0媒体类型版本Accept: application/json; v1.0GitHub 在用这种方式每种方式都有适用场景没有绝对的优劣。在 C# 生态中长期以来的事实标准是Swashbuckle.AspNetCore但它并没有内置版本管理支持需要配合Asp.Versioning来实现。终于在 .NET 10 中微软推出了自己的 OpenAPI 库Microsoft.AspNetCore.OpenApi并且Asp.Versioningv10 也正式支持了这个库版本管理和文档生成终于可以无缝结合了。上手 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 vV;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 的图和本项目无关