平时做技术实践时，很多问题不是概念不会，而是细节没串起来。拿“.NET 10 采用 Microsoft.AspNetCore.Open……”来说，它看着像小点，放到项目里常会牵出环境、配置、兼容性和维护成本。下面按实际采用顺序，把思路、关键写法和容易踩坑的地方讲清楚，便于大家直接对照操作。
为什么 API 版本管理如此重要？
理解这一步时，API 版本管理的核心目标是：在不破坏现有用户的前提下，持续迭代和改进 API。借助版本管理，我们能够：
- 引入新功能：在新版本中添加字段、接口等，而不影响旧版本的用户。
- 修复 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 的图（和本项目无关）
我把实验项目的代码放在了 GitHub 上，欢迎大家参考：
（链接已移除）
到此这篇关于.NET 10 采用 Microsoft.AspNetCore.OpenApi 实现 API 版本管理的过程详解的文章就介绍到这了,更多相关.net 采用microsoft.aspnetcore.openapi内容请搜索脚本之家以前的文章或继续浏览下面的相关文章希望大家以后多多兼容脚本之家！
- ASP.NET Core借助Microsoft.AspNetCore.App元包简化程序集引用
- .NET 6开发TodoList应用之实现API版本控制
- .NetCore采用Swagger+API多版本控制的流程分析
- ASP.NET Core WebApi版本控制的实现
- ASP.NET Core3.x API版本控制的实现
- 深入讲解.Net Core中的Api版本控制
- .Net Core Api 采用版本控制详解
- 浅谈ASP.Net Core WebApi几种版本控制对比