.Net介面版本管理與OpenApi

来源:https://www.cnblogs.com/ruipeng/p/18072151
-Advertisement-
Play Games

前言 作為開發人員，我們經常嚮應用程式添加新功能並修改當前的 Api。版本控制使我們能夠安全地添加新功能而不會造成中斷性變更。一個良好的 Api 版本控制策略可以清晰地傳達所做的更改，並允許使用現有 REST Api 的客戶端在準備好時才遷移或更新他們的應用程式到最新版本。 哪些行為可能會造成 Ap ...


前言

作為開發人員，我們經常嚮應用程式添加新功能並修改當前的 Api。版本控制使我們能夠安全地添加新功能而不會造成中斷性變更。一個良好的 Api 版本控制策略可以清晰地傳達所做的更改，並允許使用現有 REST Api 的客戶端在準備好時才遷移或更新他們的應用程式到最新版本。

哪些行為可能會造成 Api 的中斷性變更呢？

  • 刪除或重命名 Api
  • 修改 Api 參數(類型,名稱,可選參數變成非可選參數，刪除必需參數等)
  • 更改現有 Api 的行為
  • 更改 Api 響應
  • 更改 Api 錯誤代碼
  • More

我們在做開發的過程中遲早會面對 Api 版本控制需求，在 Api 開發的過程中學習如何進行版本控制是至關重要的。

本文主要介紹在 MinimalApis 進行版本控制，官網文檔在文末

藉助aspnet-api-versioning 幫助 Minimalapis 實現版本控制

開始之前在項目中安裝兩個 nuget 包:

Install-Package Asp.Versioning.Http
Install-Package Asp.Versioning.Mvc.ApiExplorer
  • Asp.Versioning.Http 用於在 MinimalApis 中提供版本控制支持
  • Asp.Versioning.Mvc.ApiExplorer 用於 OpenApi,格式化路由版本參數等

配置詳情

builder.Services.AddApiVersioning(options =>
{
    options.DefaultApiVersion = new ApiVersion(2, 0);//預設版本
    options.ReportApiVersions = true;//Response Header 指定可用版本
    options.AssumeDefaultVersionWhenUnspecified = true;//如果沒有指定版本用預設配置
    options.ApiVersionReader = ApiVersionReader.Combine(
      new QueryStringApiVersionReader("api-version"),//QueryString
      new HeaderApiVersionReader("X-Version"),//Header
      new MediaTypeApiVersionReader("ver"),//Accept MediaType
      new UrlSegmentApiVersionReader());//Route Path
}).AddApiExplorer(options =>
{
    options.GroupNameFormat = "'v'VVV";
    options.SubstituteApiVersionInUrl = true;
});

AddApiVersioning 提供了一個委托參數 Action<ApiVersioningOptions>來對 Api 版本控制配置，下麵看主要參數的配置解釋

  • DefaultApiVersion

    options.DefaultApiVersion = new ApiVersion(2,0);

    指定 Api 的預設版本以上設置為 2.0 版本，預設是 1.0

  • ReportApiVersions

     options.ReportApiVersions = true;//Response Header 指定可用版本

    在 ResponseHeader 中指定當前 Api 可用的版本 預設不開啟

  • AssumeDefaultVersionWhenUnspecified

    options.AssumeDefaultVersionWhenUnspecified = true;

    開啟後 如果 Api 不指定版本預設 DefaultApiVersion 設置版本，適合已經存在的服務開啟版本控制，幫助在不破壞現有客戶端的情況下改進現有服務並集成正式的 Api 。

  • ApiVersionReader

    
    options.ApiVersionReader = ApiVersionReader.Combine(
    new QueryStringApiVersionReader("api-version"),//QueryString 預設參數 api-vesion
    new HeaderApiVersionReader("X-Version"),//Header 預設v
    new MediaTypeApiVersionReader("ver"),//Accept MediaType 預設參數v
    new UrlSegmentApiVersionReader());//Route Path 參數v

    配置如何讀取客戶端指定的 Api 版本,預設為 QueryStringApiVersionReader 即使用名為 api-version 的查詢字元串參數。
    從上面可以看出有四種開箱即用的 Api 服務版本定義方式

    • QueryStringApiVersionReader: https://localhost:7196/api/Todo?api-version=1
    • HeaderApiVersionReader: https://localhost:7196/api/Todo -H 'X-Version: 1'
    • MediaTypeApiVersionReader:
      GET api/helloworld HTTP/2
Host: localhost
Accept: application/json;ver=1.0
    • UrlSegmentApiVersionReader: https://localhost:7196/api/workouts?api-version=1

    可以通過ApiVersionReader.Combine聯合使用。

雖然aspnet-api-versioning提供了多種版本控制的方式，但是在我們實際項目開發的過程中，我們儘可能只採用一種方案，只用一種標準可以讓我們版本開發更加的容易維護，而且多種方案配置預設策略 對 OpenApi 的集成和版本控制的預設行為都互有影響。

以上四種方案只有QueryStringApiVersionReader和UrlSegmentApiVersionReader符合 Microsoft REST Guidelines 的規範，所以我們只需要上面選一個即可.

MinimalApis 版本控制

我們採用其中的一種 來做演示看看 ApiVesioning 是如何實現的，就按預設行為 QueryStringApiVersionReader 來做一個簡單的 Demo。

創建一個 MinimalApi 的項目

VS 創建新項目->輸入項目名字然後點擊下一步-> 使用控制器的 CheckBox 確定取消勾選
.Net Cli 安裝 nuget 或者 VS 包管理器

dotnet add package Asp.Versioning.Http
dotnet add package Asp.Versioning.Mvc.ApiExplorer

Program.cs 添加預設配置

builder.Services.AddProblemDetails();
builder.Services.AddApiVersioning(options =>
{
    options.DefaultApiVersion = new ApiVersion(2, 0);//預設版本
    options.ReportApiVersions = true;//Response Header 指定可用版本
    options.AssumeDefaultVersionWhenUnspecified = true;//如果沒有指定版本用預設配置
}).AddApiExplorer(options =>
{
    options.GroupNameFormat = "'v'VVV";
    options.SubstituteApiVersionInUrl = true;
});

aspnet-api-versioning的異常處理機制依賴ProblemDetails,
所以builder.Services.AddProblemDetails();必須要註冊到 IOC 容器。
AddApiVersioning 沒有註冊任何的ApiVersionReader，所以會用預設的QueryStringApiVersionReader的模式。

AddApiExplorer 是 OpenApi 對介面格式化的策略配置

認識 幾個核心方法

  • NewVersionedApi ：創建一個路由組建造者，用於定義 Api 中所有版本化端點。

  • HasApiVersion ：表示 ApiVersionSet 支持指定的 ApiVersion。

  • HasDeprecatedApiVersion ：配置廢棄指定的 Api 版本。

  • MapToApiVersion : 將指定的 Api 版本映射到配置的端點。

  • IsApiVersionNeutral : 版本無關 也可以說任何的版本都可以訪問到這個終結點

添加 Api EndPoint


{
    var todoV1 = app.NewVersionedApi("Todo")
         .HasDeprecatedApiVersion(new ApiVersion(1, 0));//過期版本
    var todoGroup = todoV1.MapGroup("/api/Todo");
    todoGroup.MapGet("/", () => "Version 1.0").WithSummary("請用V2版本代替");
    todoGroup.MapGet("sayhello", (string name) => $"hello {name}").
}
{
    var todoV2 = app.NewVersionedApi("Todo")
                         .HasApiVersion(new ApiVersion(2, 0));
    var todoGroup = todoV2.MapGroup("/api/Todo");
    todoGroup.MapGet("/", () => "Version 2.0").MapToApiVersion(new ApiVersion(2, 0)).WithSummary("Version2");
}
{
    var todoV3 = app.NewVersionedApi("Todo")
            .HasApiVersion(new ApiVersion(3, 0));
    var todoGroup = todoV3.MapGroup("/api/Todo");
    todoGroup.MapGet("/", () => "Version 3.0").WithSummary("Version3");
    todoGroup.MapGet("sayhello", (string name) => $"hello {name}").IsApiVersionNeutral();
}

上面定義 Todo 的相關業務，當前有三個版本，V1 已經過期不推薦使用，V2 是主要版本，V3 是預覽開發版本，IsApiVersionNeutral標註了一個sayHello介面是跟版本無關的

Run 項目 測試一下

訪問 api/Todo,Options 配置了預設版本為 2.0
https://localhost:7141/api/todo 返回 Version 2.0 符合預期
image

測試 V1 版本
https://localhost:7141/api/todo?api-version=1.0
返回 Version 1.0 符合預期且 ResponseHeader 標記了過期版本和受支持的版本
image

image

測試 V2 版本
https://localhost:7141/api/todo?api-version=2.0
可以看到 返回 Version 2.0 符合預期
image

測試 V3 版本
https://localhost:7141/api/todo?api-version=3.0
可以看到 返回 Version 3.0 符合預期
image

測試 sayHello (版本無關)

  • https://localhost:7141/api/Todo/sayhello
  • https://localhost:7141/api/Todo/sayhello?name=ruipeng& api-vesion=1.0
  • https://localhost:7141/api/Todo/sayhello?name=ruipeng&api-vesion=2.0
  • https://localhost:7141/api/Todo/sayhello?name=ruipeng&api-vesion=3.0
    image

到這兒基本可以實現我們的需求了，在aspnet-api-versioning中還提供了NewApiVersionSet的方法配置添加實現 Api 的管理，大家也可以嘗試下。

版本管理對接 OpenApi

剛纔我們的項目 Run 起來之後 Swagger 首頁看到只有 V1 版本的界面,我們來設置一下讓他支持 Swagger 界面版本切換

創建 ConfigureSwaggerOptions 添加多個 SwaggerDoc

public class ConfigureSwaggerOptions(IApiVersionDescriptionProvider provider) : IConfigureOptions<SwaggerGenOptions>
{
    public void Configure(SwaggerGenOptions options)
    {
        foreach (var description in provider.ApiVersionDescriptions)
        {
            options.SwaggerDoc(description.GroupName, CreateInfoForApiVersion(description));
        }
    }

    private static OpenApiInfo CreateInfoForApiVersion(ApiVersionDescription description)
    {
        var text = new StringBuilder("An example application with OpenAPI, Swashbuckle, and API versioning.");
        var info = new OpenApiInfo()
        {
            Title = "MinimalApis With OpenApi ",
            Version = description.ApiVersion.ToString(),
            Contact = new OpenApiContact() { Name = "Ruipeng", Email = "[email protected]" },
            License = new OpenApiLicense() { Name = "MIT", Url = new Uri("https://opensource.org/licenses/MIT") }
        };

        if (description.IsDeprecated)
        {
            text.Append(" This API version has been deprecated.");
        }

        if (description.SunsetPolicy is SunsetPolicy policy)
        {
            if (policy.Date is DateTimeOffset when)
            {
                text.Append(" The API will be sunset on ")
                    .Append(when.Date.ToShortDateString())
                    .Append('.');
            }

            if (policy.HasLinks)
            {
                text.AppendLine();

                for (var i = 0; i < policy.Links.Count; i++)
                {
                    var link = policy.Links[i];

                    if (link.Type == "text/html")
                    {
                        text.AppendLine();

                        if (link.Title.HasValue)
                        {
                            text.Append(link.Title.Value).Append(": ");
                        }

                        text.Append(link.LinkTarget.OriginalString);
                    }
                }
            }
        }

        info.Description = text.ToString();

        return info;
    }
}

依賴註入

builder.Services.AddTransient<IConfigureOptions<SwaggerGenOptions>, ConfigureSwaggerOptions>();

創建攔截器

public class SwaggerDefaultValues : IOperationFilter
{
    public void Apply(OpenApiOperation operation, OperationFilterContext context)
    {
        var apiDescription = context.ApiDescription;

        operation.Deprecated |= apiDescription.IsDeprecated();

        foreach (var responseType in context.ApiDescription.SupportedResponseTypes)
        {
            var responseKey = responseType.IsDefaultResponse ? "default" : responseType.StatusCode.ToString();
            var response = operation.Responses[responseKey];

            foreach (var contentType in response.Content.Keys)
            {
                if (!responseType.ApiResponseFormats.Any(x => x.MediaType == contentType))
                {
                    response.Content.Remove(contentType);
                }
            }
        }

        if (operation.Parameters is null)
        {
            return;
        }


        foreach (var parameter in operation.Parameters)
        {
            var description = apiDescription.ParameterDescriptions.First(p => p.Name == parameter.Name);

            parameter.Description ??= description.ModelMetadata?.Description;

            if (parameter.Schema.Default is null &&
                 description.DefaultValue is not null &&
                 description.DefaultValue is not DBNull &&
                 description.ModelMetadata is ModelMetadata modelMetadata)
            {

                var json = JsonSerializer.Serialize(description.DefaultValue, modelMetadata.ModelType);
                parameter.Schema.Default = OpenApiAnyFactory.CreateFromJson(json);
            }

            parameter.Required |= description.IsRequired;
        }
    }
}

Swagger 依賴註入

builder.Services.AddSwaggerGen(options => options.OperationFilter<SwaggerDefaultValues>());

UseSwaggerUI 添加 Swagger 終結點

    app.UseSwaggerUI(options =>
    {
        var descriptions = app.DescribeApiVersions();
        // build a swagger endpoint for each discovered API version
        foreach (var description in descriptions)
        {
            var url = $"/swagger/{description.GroupName}/swagger.json";
            var name = description.GroupName.ToUpperInvariant();
            options.SwaggerEndpoint(url, name);
        }
    });

Run Swagger 查看項目

image

左上角可以成功切換版本，OpenApi 版本管理成功

最後

本文的 demo 用了aspnet-api-versioning版本控制的一種方式來做的演示，WebApi Controller 配置好 Options 之後只需要用aspnet-api-versioning提供的 Attribute 就可以實現版本管理，Route Path 和 httpHeader 等傳參數的方式只需要微調就可以實現，更多高級功能請瀏覽aspnet-api-versioning官網(文末有官網地址)。

Api 版本控制是設計現代 Api 的最佳實踐之一。從第一個版本開始實現 Api 版本控制,這樣可以更容易地讓客戶端支持未來的 Api 版本,同時也讓您的團隊習慣於管理破壞性變化和對 Api 進行版本控制。

以下是本文的完整 源代碼

aspnet-api-versioning 官網學習文檔

本文來自博客園，作者：董瑞鵬，轉載請註明原文鏈接：https://www.cnblogs.com/ruipeng/p/18072151


您的分享是我們最大的動力!

-Advertisement-
Play Games
更多相關文章
一周排行
    -Advertisement-
    Play Games
  • 移動開發（一）：使用.NET MAUI開發第一個安卓APP
    移動開發（一）：使用.NET MAUI開發第一個安卓APP 對於工作多年的C#程式員來說，近來想嘗試開發一款安卓APP，考慮了很久最終選擇使用.NET MAUI這個微軟官方的框架來嘗試體驗開發安卓APP，畢竟是使用Visual Studio開發工具，使用起來也比較的順手，結合微軟官方的教程進行了安卓 ...
  • wpf ToggleButton選中效果和一個登錄界面
    前言 QuestPDF 是一個開源 .NET 庫，用於生成 PDF 文檔。使用了C# Fluent API方式可簡化開發、減少錯誤並提高工作效率。利用它可以輕鬆生成 PDF 報告、發票、導出文件等。 項目介紹 QuestPDF 是一個革命性的開源 .NET 庫，它徹底改變了我們生成 PDF 文檔的方 ...
  • 彈幕樹洞項目功能新增篇
    項目地址 項目後端地址： https://github.com/ZyPLJ/ZYTteeHole 項目前端頁面地址： ZyPLJ/TreeHoleVue (github.com) https://github.com/ZyPLJ/TreeHoleVue 目前項目測試訪問地址： http://tree ...
  • 第27篇 sqlserver2022詳細安裝步驟
    話不多說，直接開乾 一.下載 1.官方鏈接下載： https://www.microsoft.com/zh-cn/sql-server/sql-server-downloads 2.在下載目錄中找到下麵這個小的安裝包 SQL2022-SSEI-Dev.exe，運行開始下載SQL server； 二. ...
  • .NET 開源高性能 MQTT 類庫
    前言 隨著物聯網（IoT）技術的迅猛發展，MQTT（消息隊列遙測傳輸）協議憑藉其輕量級和高效性，已成為眾多物聯網應用的首選通信標準。 MQTTnet 作為一個高性能的 .NET 開源庫，為 .NET 平臺上的 MQTT 客戶端與伺服器開發提供了強大的支持。 本文將全面介紹 MQTTnet 的核心功能 ...
  • Serilog文檔翻譯系列（六） - 可用的接收器、增強器、格式化輸出
    Serilog支持多種接收器用於日誌存儲，增強器用於添加屬性，LogContext管理動態屬性，支持多種輸出格式包括純文本、JSON及ExpressionTemplate。還提供了自定義格式化選項，適用於不同需求。 ...
  • 警惕 Visual Studio 屬性求值副作用導致邏輯不符合預期
    目錄簡介獲取 HTML 文檔解析 HTML 文檔測試參考文章 簡介 動態內容網站使用 JavaScript 腳本動態檢索和渲染數據，爬取信息時需要模擬瀏覽器行為，否則獲取到的源碼基本是空的。 本文使用的爬取步驟如下： 使用 Selenium 獲取渲染後的 HTML 文檔 使用 HtmlAgility ...
  • [使用目前最新版]HybridCLR6.9.0+YooAsset2.2.4實現純C# Unity熱更新方案 (一)
    1.前言 什麼是熱更新 游戲或者軟體更新時，無需重新下載客戶端進行安裝，而是在應用程式啟動的情況下，在內部進行資源或者代碼更新 Unity目前常用熱更新解決方案 HybridCLR，Xlua，ILRuntime等 Unity目前常用資源管理解決方案 AssetBundles，Addressable， ...
  • 在 ASP.NET Core Web API 中使用操作篩選器統一處理通用操作
    本文章主要是在C# ASP.NET Core Web API框架實現向手機發送驗證碼簡訊功能。這裡我選擇是一個互億無線簡訊驗證碼平臺，其實像阿裡雲，騰訊雲上面也可以。 首先我們先去 互億無線 https://www.ihuyi.com/api/sms.html 去註冊一個賬號 註冊完成賬號後，它會送 ...
  • 第28篇 如何.net中實現高效可靠數據同步api
    通過以下方式可以高效，並保證數據同步的可靠性 1.API設計 使用RESTful設計，確保API端點明確，並使用適當的HTTP方法（如POST用於創建，PUT用於更新）。 設計清晰的請求和響應模型，以確保客戶端能夠理解預期格式。 2.數據驗證 在伺服器端進行嚴格的數據驗證，確保接收到的數據符合預期格 ...
所有分類