经验首页 前端设计 程序设计 Java相关 移动开发 数据库/运维 软件/图像 大数据/云计算 其他经验
当前位置：技术经验 » 程序设计 » ASP.net » 查看文章
.Net接口版本管理与OpenApi
来源：cnblogs　　作者：董瑞鹏　　时间：2024/3/15 9:05:00　　对本文有异议

前言

作为开发人员，我们经常向应用程序添加新功能并修改当前的 Api。版本控制使我们能够安全地添加新功能而不会造成中断性变更。一个良好的 Api 版本控制策略可以清晰地传达所做的更改，并允许使用现有 REST Api 的客户端在准备好时才迁移或更新他们的应用程序到最新版本。

哪些行为可能会造成 Api 的中断性变更呢？

  • 删除或重命名 Api
  • 修改 Api 参数(类型,名称,可选参数变成非可选参数，删除必需参数等)
  • 更改现有 Api 的行为
  • 更改 Api 响应
  • 更改 Api 错误代码
  • More

我们在做开发的过程中迟早会面对 Api 版本控制需求，在 Api 开发的过程中学习如何进行版本控制是至关重要的。

本文主要介绍在 MinimalApis 进行版本控制，官网文档在文末

借助aspnet-api-versioning 帮助 Minimalapis 实现版本控制

开始之前在项目中安装两个 nuget 包:

  1. Install-Package Asp.Versioning.Http
  2. Install-Package Asp.Versioning.Mvc.ApiExplorer
  • Asp.Versioning.Http 用于在 MinimalApis 中提供版本控制支持
  • Asp.Versioning.Mvc.ApiExplorer 用于 OpenApi,格式化路由版本参数等

配置详情

  1. builder.Services.AddApiVersioning(options =>
  2. {
  3.     options.DefaultApiVersion = new ApiVersion(2, 0);//默认版本
  4.     options.ReportApiVersions = true;//Response Header 指定可用版本
  5.     options.AssumeDefaultVersionWhenUnspecified = true;//如果没有指定版本用默认配置
  6.     options.ApiVersionReader = ApiVersionReader.Combine(
  7.       new QueryStringApiVersionReader("api-version"),//QueryString
  8.       new HeaderApiVersionReader("X-Version"),//Header
  9.       new MediaTypeApiVersionReader("ver"),//Accept MediaType
  10.       new UrlSegmentApiVersionReader());//Route Path
  11. }).AddApiExplorer(options =>
  12. {
  13.     options.GroupNameFormat = "'v'VVV";
  14.     options.SubstituteApiVersionInUrl = true;
  15. });

AddApiVersioning 提供了一个委托参数 Action<ApiVersioningOptions>来对 Api 版本控制配置，下面看主要参数的配置解释

  • DefaultApiVersion

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

    指定 Api 的默认版本以上设置为 2.0 版本，默认是 1.0

  • ReportApiVersions

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

    在 ResponseHeader 中指定当前 Api 可用的版本 默认不开启

  • AssumeDefaultVersionWhenUnspecified

    1. options.AssumeDefaultVersionWhenUnspecified = true;

    开启后 如果 Api 不指定版本默认 DefaultApiVersion 设置版本，适合已经存在的服务开启版本控制，帮助在不破坏现有客户端的情况下改进现有服务并集成正式的 Api 。

  • ApiVersionReader

    2.     options.ApiVersionReader = ApiVersionReader.Combine(
    3.     new QueryStringApiVersionReader("api-version"),//QueryString 默认参数 api-vesion
    4.     new HeaderApiVersionReader("X-Version"),//Header 默认v
    5.     new MediaTypeApiVersionReader("ver"),//Accept MediaType 默认参数v
    6.     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:
      1. GET api/helloworld HTTP/2
      2. Host: localhost
      3. 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 包管理器

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

Program.cs 添加默认配置

  1. builder.Services.AddProblemDetails();
  2. builder.Services.AddApiVersioning(options =>
  3. {
  4.     options.DefaultApiVersion = new ApiVersion(2, 0);//默认版本
  5.     options.ReportApiVersions = true;//Response Header 指定可用版本
  6.     options.AssumeDefaultVersionWhenUnspecified = true;//如果没有指定版本用默认配置
  7. }).AddApiExplorer(options =>
  8. {
  9.     options.GroupNameFormat = "'v'VVV";
  10.     options.SubstituteApiVersionInUrl = true;
  11. });

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

  2. {
  3.     var todoV1 = app.NewVersionedApi("Todo")
  4.          .HasDeprecatedApiVersion(new ApiVersion(1, 0));//过期版本
  5.     var todoGroup = todoV1.MapGroup("/api/Todo");
  6.     todoGroup.MapGet("/", () => "Version 1.0").WithSummary("请用V2版本代替");
  7.     todoGroup.MapGet("sayhello", (string name) => $"hello {name}").
  8. }
  9. {
  10.     var todoV2 = app.NewVersionedApi("Todo")
  11.                          .HasApiVersion(new ApiVersion(2, 0));
  12.     var todoGroup = todoV2.MapGroup("/api/Todo");
  13.     todoGroup.MapGet("/", () => "Version 2.0").MapToApiVersion(new ApiVersion(2, 0)).WithSummary("Version2");
  14. }
  15. {
  16.     var todoV3 = app.NewVersionedApi("Todo")
  17.             .HasApiVersion(new ApiVersion(3, 0));
  18.     var todoGroup = todoV3.MapGroup("/api/Todo");
  19.     todoGroup.MapGet("/", () => "Version 3.0").WithSummary("Version3");
  20.     todoGroup.MapGet("sayhello", (string name) => $"hello {name}").IsApiVersionNeutral();
  21. }

上面定义 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

  1. public class ConfigureSwaggerOptions(IApiVersionDescriptionProvider provider) : IConfigureOptions<SwaggerGenOptions>
  2. {
  3.     public void Configure(SwaggerGenOptions options)
  4.     {
  5.         foreach (var description in provider.ApiVersionDescriptions)
  6.         {
  7.             options.SwaggerDoc(description.GroupName, CreateInfoForApiVersion(description));
  8.         }
  9.     }
  11.     private static OpenApiInfo CreateInfoForApiVersion(ApiVersionDescription description)
  12.     {
  13.         var text = new StringBuilder("An example application with OpenAPI, Swashbuckle, and API versioning.");
  14.         var info = new OpenApiInfo()
  15.         {
  16.             Title = "MinimalApis With OpenApi ",
  17.             Version = description.ApiVersion.ToString(),
  18.             Contact = new OpenApiContact() { Name = "Ruipeng", Email = "478083649@qq.com" },
  19.             License = new OpenApiLicense() { Name = "MIT", Url = new Uri("https://opensource.org/licenses/MIT") }
  20.         };
  22.         if (description.IsDeprecated)
  23.         {
  24.             text.Append(" This API version has been deprecated.");
  25.         }
  27.         if (description.SunsetPolicy is SunsetPolicy policy)
  28.         {
  29.             if (policy.Date is DateTimeOffset when)
  30.             {
  31.                 text.Append(" The API will be sunset on ")
  32.                     .Append(when.Date.ToShortDateString())
  33.                     .Append('.');
  34.             }
  36.             if (policy.HasLinks)
  37.             {
  38.                 text.AppendLine();
  40.                 for (var i = 0; i < policy.Links.Count; i++)
  41.                 {
  42.                     var link = policy.Links[i];
  44.                     if (link.Type == "text/html")
  45.                     {
  46.                         text.AppendLine();
  48.                         if (link.Title.HasValue)
  49.                         {
  50.                             text.Append(link.Title.Value).Append(": ");
  51.                         }
  53.                         text.Append(link.LinkTarget.OriginalString);
  54.                     }
  55.                 }
  56.             }
  57.         }
  59.         info.Description = text.ToString();
  61.         return info;
  62.     }
  63. }

依赖注入

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

创建拦截器

  1. public class SwaggerDefaultValues : IOperationFilter
  2. {
  3.     public void Apply(OpenApiOperation operation, OperationFilterContext context)
  4.     {
  5.         var apiDescription = context.ApiDescription;
  7.         operation.Deprecated |= apiDescription.IsDeprecated();
  9.         foreach (var responseType in context.ApiDescription.SupportedResponseTypes)
  10.         {
  11.             var responseKey = responseType.IsDefaultResponse ? "default" : responseType.StatusCode.ToString();
  12.             var response = operation.Responses[responseKey];
  14.             foreach (var contentType in response.Content.Keys)
  15.             {
  16.                 if (!responseType.ApiResponseFormats.Any(x => x.MediaType == contentType))
  17.                 {
  18.                     response.Content.Remove(contentType);
  19.                 }
  20.             }
  21.         }
  23.         if (operation.Parameters is null)
  24.         {
  25.             return;
  26.         }
  29.         foreach (var parameter in operation.Parameters)
  30.         {
  31.             var description = apiDescription.ParameterDescriptions.First(p => p.Name == parameter.Name);
  33.             parameter.Description ??= description.ModelMetadata?.Description;
  35.             if (parameter.Schema.Default is null &&
  36.                  description.DefaultValue is not null &&
  37.                  description.DefaultValue is not DBNull &&
  38.                  description.ModelMetadata is ModelMetadata modelMetadata)
  39.             {
  41.                 var json = JsonSerializer.Serialize(description.DefaultValue, modelMetadata.ModelType);
  42.                 parameter.Schema.Default = OpenApiAnyFactory.CreateFromJson(json);
  43.             }
  45.             parameter.Required |= description.IsRequired;
  46.         }
  47.     }
  48. }

Swagger 依赖注入

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

UseSwaggerUI 添加 Swagger 终结点

  1.     app.UseSwaggerUI(options =>
  2.     {
  3.         var descriptions = app.DescribeApiVersions();
  4.         // build a swagger endpoint for each discovered API version
  5.         foreach (var description in descriptions)
  6.         {
  7.             var url = $"/swagger/{description.GroupName}/swagger.json";
  8.             var name = description.GroupName.ToUpperInvariant();
  9.             options.SwaggerEndpoint(url, name);
  10.         }
  11.     });

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

 友情链接：直通硅谷 　点职佳 　北美留学生论坛

ASP.net热门文章

  • 【Dotnet 工具箱】WPF UI - 现代化设计的开源 WPF 框架
  • net core 使用 SqlSugar
  • .NETCore下CI/CD之自动化测试
  • .net core部署到linux可能碰到的问题
  • Abp vNext 自定义 Ef Core 仓储引发异常
  • .NetCore 消息队列的使用
  • .NetCore WebApi——基于JWT的简单身份认证与授权（Swagger）
  • Abp.NHibernate连接PostgreSQl数据库
  • ModelValidator基于元数据的验证
  • .NET MAUI 安卓应用开发初体验

    • ASP.net推荐文章

  • Gradio.NET 支持 .NET 8 简化 Web 应用开发
  • .NET 轻量化定时任务调度 FreeScheduler
  • WPF 模仿前端大佬写一个Hover效果
  • WPF 模拟UWP原生窗口样式——亚克力|云母材质、自定义标题栏样式、原生DWM动画 （附我封装好的类）
  • .NET 音频采集
  • .NET8 Blazor 从入门到精通：（三）类库和表单
  • wpf 如何7步写一个badge控件
  • .NET 高效Nuget管理工具（开源）
  • .NET 8 跨平台高性能边缘采集网关
  • .NET 窗口/屏幕录制

    • 本站QQ群：前端 618073944 | Java 606181507 | Python 626812652 | C/C++ 612253063 | 微信 634508462 | 苹果 692586424 | C#/.net 182808419 | PHP 305140648 | 运维 608723728

    W3xue 的所有内容仅供测试，对任何法律问题及风险不承担任何责任。通过使用本站内容随之而来的风险与本站无关。
    关于我们  |  意见建议  |  捐助我们  |  报错有奖  |  广告合作、友情链接（目前9元/月）请联系QQ：27243702 沸活量
    皖ICP备17017327号-2　皖公网安备34020702000426号