為什么 API 版本管理如此重要？

API 版本管理的核心目標(biāo)是：在不破壞現(xiàn)有用戶的前提下，持續(xù)迭代和改進(jìn) API。通過(guò)版本管理，我們可以：

• 引入新功能：在新版本中添加字段、接口等，而不影響舊版本的用戶。
• 修復(fù) bug：在新版本中修復(fù)問(wèn)題，而不冒破壞舊版本的風(fēng)險(xiǎn)。
• 逐步淘汰：在新版本中移除過(guò)時(shí)的功能，給用戶足夠的時(shí)間遷移。

常見(jiàn)的版本策略有這幾種：

• URL 路徑版本：/api/v1/users，直觀，最常見(jiàn)
• 查詢參數(shù)版本：/api/users?api-version=1.0
• 請(qǐng)求頭版本：X-API-Version: 1.0
• 媒體類型版本：Accept: application/json; v=1.0（GitHub 在用這種方式）

每種方式都有適用場(chǎng)景，沒(méi)有絕對(duì)的優(yōu)劣。

在 C# 生態(tài)中，長(zhǎng)期以來(lái)的事實(shí)標(biāo)準(zhǔn)是 Swashbuckle.AspNetCore，但它并沒(méi)有內(nèi)置版本管理支持，需要配合 Asp.Versioning 來(lái)實(shí)現(xiàn)。

終于，在 .NET 10 中，微軟推出了自己的 OpenAPI 庫(kù) Microsoft.AspNetCore.OpenApi，并且 Asp.Versioning v10 也正式支持了這個(gè)庫(kù)，版本管理和文檔生成終于可以無(wú)縫結(jié)合了。

上手 Microsoft.AspNetCore.OpenApi 和 Asp.Versioning

要使用 Microsoft.AspNetCore.OpenApi 和 Asp.Versioning 來(lái)實(shí)現(xiàn) API 版本管理，首先需要安裝相關(guān) 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 中進(jìn)行如下配置：

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 版本管理，指定了默認(rèn)版本、版本讀取方式等。然后，我們?yōu)槊總€(gè)版本配置了 OpenAPI 文檔生成，確保每個(gè)版本都有獨(dú)立的文檔。最后，我們映射了 OpenAPI 和 Scalar API Reference 的路由。

控制器方面，我們可以使用特性來(lái)指定版本：

[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" } });
    }
}

通過(guò)上述配置，我們就實(shí)現(xiàn)了基于 URL 路徑的 API 版本管理，并且每個(gè)版本都有獨(dú)立的 OpenAPI 文檔。

這里還使用了一個(gè)叫 Scalar 的庫(kù)來(lái)生成 API 參考文檔。Scalar 是一個(gè)專注于生成 API 參考文檔的庫(kù)，支持多版本文檔生成和定制化配置。通過(guò) Scalar，我們可以輕松地為每個(gè) API 版本生成漂亮的參考文檔，方便開(kāi)發(fā)者查閱。

上一張 Scalar 的圖（和本項(xiàng)目無(wú)關(guān)）

我把實(shí)驗(yàn)項(xiàng)目的代碼放在了 GitHub 上，歡迎大家參考：
https://github.com/denglei1024/openapi-apiversion

到此這篇關(guān)于.NET 10 使用 Microsoft.AspNetCore.OpenApi 實(shí)現(xiàn) API 版本管理的過(guò)程詳解的文章就介紹到這了,更多相關(guān).net 使用microsoft.aspnetcore.openapi內(nèi)容請(qǐng)搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關(guān)文章希望大家以后多多支持腳本之家！

最新評(píng)論