.Net接口版本管理与OpenApi

这篇具有很好参考价值的文章主要介绍了.Net接口版本管理与OpenApi。希望对大家有所帮助。如果存在错误或未考虑完全的地方,请大家不吝赐教,您也可以点击"举报违法"按钮提交疑问。

前言

作为开发人员,我们经常向应用程序添加新功能并修改当前的 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 的集成和版本控制的默认行为都互有影响。

以上四种方案只有QueryStringApiVersionReaderUrlSegmentApiVersionReader符合 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的模式。

AddApiExplorerOpenApi 对接口格式化的策略配置

认识 几个核心方法

  • 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 符合预期
.Net接口版本管理与OpenApi


测试 V1 版本
https://localhost:7141/api/todo?api-version=1.0
返回 Version 1.0 符合预期且 ResponseHeader 标记了过期版本和受支持的版本
.Net接口版本管理与OpenApi

.Net接口版本管理与OpenApi


测试 V2 版本
https://localhost:7141/api/todo?api-version=2.0
可以看到 返回 Version 2.0 符合预期
.Net接口版本管理与OpenApi


测试 V3 版本
https://localhost:7141/api/todo?api-version=3.0
可以看到 返回 Version 3.0 符合预期
.Net接口版本管理与OpenApi


测试 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
    .Net接口版本管理与OpenApi

到这儿基本可以实现我们的需求了,在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 = "478083649@qq.com" },
            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 查看项目

.Net接口版本管理与OpenApi

左上角可以成功切换版本,OpenApi 版本管理成功

最后

本文的 demo 用了aspnet-api-versioning版本控制的一种方式来做的演示,WebApi Controller 配置好 Options 之后只需要用aspnet-api-versioning提供的 Attribute 就可以实现版本管理,Route PathhttpHeader 等传参数的方式只需要微调就可以实现,更多高级功能请浏览aspnet-api-versioning官网(文末有官网地址)。

Api 版本控制是设计现代 Api 的最佳实践之一。从第一个版本开始实现 Api 版本控制,这样可以更容易地让客户端支持未来的 Api 版本,同时也让您的团队习惯于管理破坏性变化和对 Api 进行版本控制。

以下是本文的完整 源代码

aspnet-api-versioning 官网学习文档文章来源地址https://www.toymoban.com/news/detail-839709.html

到了这里,关于.Net接口版本管理与OpenApi的文章就介绍完了。如果您还想了解更多内容,请在右上角搜索TOY模板网以前的文章或继续浏览下面的相关文章,希望大家以后多多支持TOY模板网!

本文来自互联网用户投稿,该文观点仅代表作者本人,不代表本站立场。本站仅提供信息存储空间服务,不拥有所有权,不承担相关法律责任。如若转载,请注明出处: 如若内容造成侵权/违法违规/事实不符,请点击违法举报进行投诉反馈,一经查实,立即删除!

领支付宝红包 赞助服务器费用

相关文章

  • .NET 高级开发人员面试常见问题及解答

    当面试.NET高级开发人员时,面试官通常会围绕技术深度、问题解决能力、项目经验以及编程理念等方面提出问题。以下是20个常见的面试问题及其详细解答: 问题:请简述ASP.NET MVC的工作原理? 解答:ASP.NET MVC是一个基于MVC(模型-视图-控制器)设计模式的Web应用程序框架。

    2024年04月26日
    浏览(48)
  • 基于Android Studio开发的人员管理系统APP

    目录 人员管理系统 前言 一、系统的大概流程 二、详细开发步骤 1.登陆界面 2.中间跳转界面 3.添加用户 4.全部用户界面  5.项目下载 总结 这是一个具有登录功能和人员信息增删改查功能的人员管理系统,在之前也有做过一个通过http协议与云平台对接的app,正好需要完成一个

    2024年02月07日
    浏览(70)
  • OpenApi接口的一次调用经历(附代码)

    去弄一个api_key:https://platform.openai.com/account/api-keys   先看所有能用的模型: 返回: babbage davinci text-davinci-edit-001 babbage-code-search-code text-similarity-babbage-001 code-davinci-edit-001 text-davinci-001 ada curie-instruct-beta babbage-code-search-text babbage-similarity whisper-1 code-search-babbage-text-001 text-curie-

    2024年02月12日
    浏览(50)
  • PHP实现OpenApi接口ChatGPT回复输出流文字流打字效果

    在做AI聊天时,回复文字时一般用实时打字文字流效果,那PHP实现ChatGPT回复输出流文字流打字效果怎么实现呢? 先看一下效果图: 注意看一下前端ajax请求是EventStream类型。具体什么是EventStream百度了解。 后端PHP配置和实现

    2024年02月12日
    浏览(41)
  • Rx.NET in Action 中文介绍 前言及序言

    目标 可选方式 Rx 处理器(Operator) 创建 Observable Creating Observables 直接创建 By explicit logic Create Defer 根据范围创建 By specification Range Repeat Generate Timer Interval Return 使用预设 Predefined primitives Throw Never Empty 从其他类型创建 From other types FromEventPattern FromEvent FromTask FromAsync 变换 Transform

    2024年02月13日
    浏览(51)
  • API攻防-接口安全&SOAP&OpenAPI&RESTful&分类特征导入&项目联动检测

    接口是后端设计的一套供给第三方使用的方法 举个例子,fofa提供了第三方api接口来进行调用,使用查询语法获取资产目标资产信息 输入相关参数进行调用 API安全就是围绕着这一个接口进行的,可能存在的漏洞包括:SQL注入、身份验证、信息泄漏、XSS跨站等 Web Service是基于网

    2024年02月07日
    浏览(49)
  • .NET Evolve 数据库版本管理工具

    提到数据库版本管理, Java 领域开发首先会想到大名鼎鼎的 flyway 。但是它不适用 .NET 领域,那么 .NET 领域也需要做数据库版本管理,该用什么工具?自行造轮子? .NET 领域的解决方案就是 Evolve ,这是一个开源库。[仓库地址](GitHub - lecaillon/Evolve: Database migration tool for .NET an

    2024年02月12日
    浏览(73)
  • 【微信公众号】15、SpringBoot整合WxJava实现openApi管理

    1、清空api的调用quota 本接口用于清空公众号/小程序/第三方平台等接口的每日调用接口次数 注意事项: 如果要清空公众号的接口的quota,则需要用公众号的access_token;如果要清空小程序的接口的quota,则需要用小程序的access_token;如果要清空第三方平台的接口的quota,则需要

    2024年02月16日
    浏览(49)
  • AutoCAD二次开发(ObjectARX/.NET) 多版本开发包兼容性

    文章来源:General Development Compatibility 一般开发兼容性 (ObjectARX/.NET) - 中文CAD开发文档,CAD二次开发问题交流,优秀插件分享  产品发布 二进制兼容版本 支持的开发环境 AutoCAD 2021 AutoCAD 2021 Windows Visual Studio 2019 Mac OS(10.13 或更高版本) Xcode : 10.2.1 Mono : 5.20.1.19 AutoCAD 202

    2024年01月20日
    浏览(53)
  • 每个.NET开发都应掌握的C#接口知识点

    作为.NET开发者,接口是C#必须掌握的知识点,接口是C#中实现多态和组件间互操作性的关键机制之一。 接口是一种抽象的类型,它定义了一组成员(方法、属性、事件等)的规范,但没有实现代码。类可以实现一个或多个接口,以表明它们提供了特定的功能。 以下是每个.N

    2024年02月13日
    浏览(47)

觉得文章有用就打赏一下文章作者

支付宝扫一扫打赏

博客赞助

微信扫一扫打赏

请作者喝杯咖啡吧~博客赞助

支付宝扫一扫领取红包,优惠每天领

二维码1

领取红包

二维码2

领红包