ASP.NET Core WebApi版本控制

作者:神秘网友 发布时间:2021-02-21 17:20:05

ASP.NET Core WebApi版本控制

前言:

 在日常项目开发中,随着项目需求不断的累加、不断的迭代;项目服务接口需要向下兼容历史版本;前些时候就因为Api接口为做版本管理导致接口对低版本兼容处理不友好。

 最近就像了解下如何实现WebApi版本控制,那么版本控制有什么好处呢

 WebApi版本控制的好处

  • 有助于及时推出功能, 而不会破坏现有系统,兼容性处理更友好。
  • 它还可以帮助为选定的客户提供额外的功能。

 接下来就来实现版本控制以及在Swagger UI中接入WebApi版本

一、WebApi版本控制实现

  通过Microsoft.AspNetCore.Mvc.Versioning实现webapi 版本控制

  • 创建WebApi项目,添加Nuget包:Microsoft.AspNetCore.Mvc.Versioning
Install-Package Microsoft.AspNetCore.Mvc.Versioning 
  • 修改项目Startup文件,使用Microsoft.AspNetCore.Mvc.Versioning
public class Startup
{
    public Startup(IConfiguration configuration)
    {
        Configuration = configuration;
    }
    public IConfiguration Configuration { get; }

    // This method gets called by the runtime. Use this method to add services to the container.
    public void ConfigureServices(IServiceCollection services)
    {
        //根据需要设置,以下内容
        services.AddApiVersioning(apiOtions =
        {
            //返回响应标头中支持的版本信息
            apiOtions.ReportApiVersions = true;
            //此选项将用于不提供版本的请求。默认情况下, 假定的 API 版本为1.0
            apiOtions.AssumeDefaultVersionWhenUnspecified = true;
            //缺省api版本号,支持时间或数字版本号
            apiOtions.DefaultApiVersion = new ApiVersion(1, 0);
            //支持MediaType、Header、QueryString 设置版本号;缺省为QueryString、UrlSegment设置版本号;后面会详细说明对于作用
            apiOtions.ApiVersionReader = ApiVersionReader.Combine(
                new MediaTypeApiVersionReader("api-version"),
                new HeaderApiVersionReader("api-version"),
                new QueryStringApiVersionReader("api-version"),
                new UrlSegmentApiVersionReader());
        });
        services.AddControllers();
    }

    // This method gets called by the runtime. Use this method to configure the HTTP request pipeline.
    public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
    {
        if (env.IsDevelopment())
        {
            app.UseDeveloperExceptionPage();
        }
        app.UseHttpsRedirection();

        //使用ApiVersioning
        app.UseApiVersioning();
app.UseRouting(); app.UseAuthorization(); app.UseEndpoints(endpoints = { endpoints.MapControllers(); }); } }
  • WebApi设置版本:

  a)通过ApiVersion标记指定指定控制器或方法的版本号;Url参数控制版本(QueryStringApiVersionReader),如下:

namespace WebAPIVersionDemo.Controllers
{
    [ApiController]
    [Route("[controller]")]
    //Deprecated=true:表示v1即将弃用,响应头中返回
    [ApiVersion("1.0", Deprecated = true)]
    [ApiVersion("2.0")]public class WeatherForecastController : ControllerBase
    {
        private static readonly string[] Summaries = new[]{"Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching"};
 
        [HttpGet]
        public IEnumerableWeatherForecast Get()
        {
            var rng = new Random();
            return Enumerable.Range(1, 5).Select(index = new WeatherForecast
            {
                Date = DateTime.Now.AddDays(index),
                TemperatureC = rng.Next(-20, 55),
                Summary = $"v1:{Summaries[rng.Next(Summaries.Length)]}"
            })
            .ToArray();
        }        
    }
}

  通过参数api-version参数指定版本号;调用结果:

  

  b)通过Url Path Segment控制版本号(UrlSegmentApiVersionReader):为控制器添加路由方式如下,apiVersion为固定格式  

[Route("/api/v{version:apiVersion}/[controller]")]

  调用方式:通过调用路径传入版本号,如:http://localhost:5000/api/v1/weatherforecast

   

  c)通过Header头控制版本号:在Startup中设置(HeaderApiVersionReader、MediaTypeApiVersionReader

apiOtions.ApiVersionReader = ApiVersionReader.Combine(
                new MediaTypeApiVersionReader("api-version"),
                new HeaderApiVersionReader("api-version"));

  调用方式,在请求头或中MediaType中传递api版本,如下:

   

   

  • 其他说明:

    a)ReportApiVersions设置为true时, 返回当前支持版本号(api-supported-versions);Deprecated 参数设置为true表示已弃用,在响应头中也有显示(api-deprecated-versions):

    

    b)MapToApiVersion标记:允许将单个API操作映射到任何版本(可以在v1的控制器中添加v3的方法);在上面控制器中添加以下代码,访问v3版本方法

[HttpGet]
[MapToApiVersion("3.0")]
public IEnumerableWeatherForecast GetV3()
{
    //获取版本
    string v = HttpContext.GetRequestedApiVersion().ToString();
    var rng = new Random();
    return Enumerable.Range(1, 1).Select(index = new WeatherForecast
    {
        Date = DateTime.Now.AddDays(index),
        TemperatureC = rng.Next(-20, 55),
        Summary = $"v{v}:{Summaries[rng.Next(Summaries.Length)]}"
    })
    .ToArray();
}

    

   c)注意事项:

    1、路径中参数版本高于,其他方式设置版本

    2、多种方式传递版本,只能采用一种方式传递版本号

    3、SwaggerUI中MapToApiVersion设置版本不会单独显示    

二、Swagger UI中版本接入

 1、添加包:Swashbuckle.AspNetCore、Microsoft.AspNetCore.Mvc.Versioning.ApiExplorer  

//swaggerui 包
Install-Package Swashbuckle.AspNetCore
//api版本
Install-Package Microsoft.AspNetCore.Mvc.Versioning.ApiExplorer 

 2、修改Startup代码:

public class Startup
{
    /// summary
    /// Api版本提者信息
    /// /summary
    private IApiVersionDescriptionProvider provider;

    // This method gets called by the runtime. Use this method to add services to the container.
    public void ConfigureServices(IServiceCollection services)
    {
        services.AddControllers();
          
        //根据需要设置,以下内容
        services.AddApiVersioning(apiOtions =
        {
            //返回响应标头中支持的版本信息
            apiOtions.ReportApiVersions = true;
            //此选项将用于不提供版本的请求。默认情况下, 假定的 API 版本为1.0
            apiOtions.AssumeDefaultVersionWhenUnspecified = true;
            //缺省api版本号,支持时间或数字版本号
            apiOtions.DefaultApiVersion = new ApiVersion(1, 0);
            //支持MediaType、Header、QueryString 设置版本号;缺省为QueryString设置版本号
            apiOtions.ApiVersionReader = ApiVersionReader.Combine(
                    new MediaTypeApiVersionReader("api-version"),
                    new HeaderApiVersionReader("api-version"),
                    new QueryStringApiVersionReader("api-version"),
                    new UrlSegmentApiVersionReader());
        });


        services.AddVersionedApiExplorer(option =
        {
            option.GroupNameFormat = "接口:'v'VVV";
            option.AssumeDefaultVersionWhenUnspecified = true;
        });

        this.provider = services.BuildServiceProvider().GetRequiredServiceIApiVersionDescriptionProvider();
        services.AddSwaggerGen(options =
        {
            foreach (var description in provider.ApiVersionDescriptions)
            {
                options.SwaggerDoc(description.GroupName,
                        new Microsoft.OpenApi.Models.OpenApiInfo()
                        {
                            Title = $"接口 v{description.ApiVersion}",
                            Version = description.ApiVersion.ToString(),
                            Description = "切换版本请点右上角版本切换"
                        }
                );
            }
            options.IncludeXmlComments(this.GetType().Assembly.Location.Replace(".dll", ".xml"), true);
        });

    }

    // This method gets called by the runtime. Use this method to configure the HTTP request pipeline.
    public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
    {
        //……    
   
        //使用ApiVersioning
        app.UseApiVersioning();

        //启用swaggerui,绑定api版本信息
        app.UseSwagger();
        app.UseSwaggerUI(c =
        {
            foreach (var description in provider.ApiVersionDescriptions)
            {
                c.SwaggerEndpoint($"/swagger/{description.GroupName}/swagger.json", description.GroupName.ToUpperInvariant());
            }
        });

        //……    
    }
}

 3、运行效果:  

  

其他: 

 示例地址:https://github.com/cwsheng/WebAPIVersionDemo

ASP.NET Core WebApi版本控制 相关文章

  1. .net5 core webapi进阶之一:System.Text.Json的用法详解

    从本篇开始写 .net5 core webapi 进阶系列,先从JSON这种数据格式开始,原因如下: 1 . 够简洁; 2 . 易于理解; 3 . 其格式和面向对象的语言天然匹配; 4 . 多语言(Javascript 、C# 、Java 等)支持; 毫无疑问,JSON是不同语言,不同系统之间进行数据交换

  2. ASP.NET Core 跨域

    跨域常见问题: 1.发布到IIS上后跨域问题 解决方法 修改web.config文件 system.webServer httpProtocol customHeaders add name="Access-Control-Allow-Methods" value="GET,POST,PUT,DELETE,OPTIONS" / add name="Access-Control-Allow-Headers" value="con

  3. CorelDRAW(CDR)2019 安装教程,附序列号!

    下载地址:https://mp.weixin.qq.com/s/A7HhCWUsVN47x1ISOa6fAg 今天带大家一起安装jihuo的是一款强大的矢量图形制作工具软件——【CorelDRAW】(亲测有效!!!)。 01CoreIDRAW简介 CorelDRAW Graphics Suite是加拿大Corel公司的平面设计软件;该软件是Cor

  4. .net core 和 WPF 开发升讯威在线客服系统:怎样实现拔网线也不丢消息的高可靠通信(附视频)

    本系列文章详细介绍使用 .net core 和 WPF 开发 升讯威在线客服与营销系统 的过程。本产品已经成熟稳定并投入商用。 在线演示环境:https://kf.shengxunwei.com 注意:演示环境仅供演示交流与评估,不保证 7x24 小时可用。 文章目录列表请点击这里 演示网络

  5. .Net Core 3.1浏览器后端服务(三) Swagger引入与应用

    一、前言 前后端分离的软件开发方式已逐步成为互联网项目开发的业界标准,前后端分离带来了诸多好处的同时,也带来了一些弊端。 接口文档的维护就是其中之一,起初前后端约定文档规范,开发的很愉快,随着时间推移、版本迭代、接口更改,接口文档维护越来越

  6. 了解ASP.NET MVC几种ActionResult的本质:FileResult

    FileResult是一个基于文件的ActionResult,利用FileResult我们可以很容易地将从某个物理文件的内容响应给客户端。ASP.NET MVC定义了三个具体的FileResult,分别是FileContentResult、FilePathResult和FileStreamResult。在这篇文章中我们将探讨三种具体的Fil

  7. 彻底解决Asp.netCore WebApi 3.1 跨域时的预检查204 options重复请求的问题

    Asp.netCore WebApi 3.1 跨域的预检查options问题 1:我们直接使用core跨域的中间件 ,注入跨域服务, services.AddCors(options = { // CorsPolicy 是自訂的 Policy 名稱 options.AddPolicy("CorsPolicy", policy = { policy.SetPreflightMaxAge(TimeSpan.F

  8. .Net Core 的项目部署Docker

    说明下:部署的方法有很多种这只是其中的一种,不要乱喷~~~不知道说啥 直接上图项目结构: 文件目录结构:项目dockerfile文件是在项目根目录的 项目说明 :WebApplication1 是有引用类库ClassLrary1 ,WebApplication2没有任何引用 把项目部署在docker上面的

  9. 在Windows上远程调试Ubuntu-Arm上的.Netcore

    在 Linux 上使用 SSH 通过附加到进程调试 .NET Core 自 Visual Studio 2017 起,可以通过 SSH 附加到在本地或远程 Linux 部署上运行的 .NET Core 进程。 本文介绍调试的设置方法和调试方法。 有关使用 Docker 容器的调试方案,请参阅附加到在 Docker 容器上

  10. netCore微服务学习笔记(二):NetCore Ocelot Api网关

    一.API网关 API网关 二.Ocelot简介 Ocelot是.net下开源的API网关,它实现了包括路由,认证、授权、服务发现、负载均衡、限流熔断等功能;具体可以参照文档Ocelot;Ocelot各个功能的实现,都是通过json配置文件来实现的,配置文件基本格式如下: { "Routes": [

每天更新java,php,javaScript,go,python,nodejs,vue,android,mysql等相关技术教程,教程由网友分享而来,欢迎大家分享IT技术教程到本站,帮助自己同时也帮助他人!

Copyright 2020, All Rights Reserved. Powered by 跳墙网(www.tqwba.com)|网站地图|关键词