.NET 10 使用 Microsoft.AspNetCore.OpenApi 实现 API 版本管理

API 版本管理是后端接口迭代的核心保障，能够实现接口平滑更新，在不破坏原有业务和用户调用逻辑的前提下，完成功能新增、漏洞修复与废弃接口淘汰。行业主流包含四种版本控制策略，而.NET 生态在迭代至.NET 10 后，依托全新官方 OpenApi 库，实现了 API 版本管理与接口文档的无缝融合，大幅提升开发规范性。

为什么 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 文档。

综上所述，规范的 API 版本管理是系统持续迭代、稳定运行的关键。借助.NET 10 全新的官方组件搭配 Asp.Versioning，可快速实现多版本 API 隔离与独立文档生成。结合 Scalar 可视化接口文档，彻底解决了传统版本管理配置繁琐、文档同步困难的问题，为.NET 项目接口标准化迭代提供了高效落地方案。

以上关于.NET 10 使用 Microsoft.AspNetCore.OpenApi 实现 API 版本管理的文章就介绍到这了，更多相关内容请搜索码云笔记以前的文章或继续浏览下面的相关文章，希望大家以后多多支持码云笔记。