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 IEnumerable<WeatherForecast> 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 IEnumerable<WeatherForecast> 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().GetRequiredService<IApiVersionDescriptionProvider>();
    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版本控制的实现的文章就介绍到这了,更多相关ASP.NET Core WebApi版本控制内容请搜索真格学网以前的文章或继续浏览下面的相关文章希望大家以后多多支持真格学网!

您可能感兴趣的文章:浅谈ASP.Net Core WebApi几种版本控制对比

  • 本文相关:
  • xaml: 自定义控件中事件处理的最佳实践方法
  • asp.net 下载文件时输出文件内容
  • asp.net多彩下拉框开发实例
  • asp.net 获取图片高度和宽度实例代码
  • asp.net2.0 sql server数据库连接详解
  • asp.net使用jquery模板引擎jtemplates呈现表格
  • asp.net mvc开发之删除修改数据
  • .net core 实现微信小程序支付功能(统一下单)
  • asp.net 下载功能的解决方案
  • asp.net文件处理如何操作
  • 如何让webapi的版本降为.net4.0
  • asp.net WebAPI问题(急)
  • asp.net mvc3 项目怎么开发API接口?
  • asp.net webapi 控制器里面的post方法是怎么把json...
  • 如何在ASP NET Core中实现CORS跨域
  • c#一个解决方案里包含.netcore3.1和asp.net两个项...
  • asp.net WebAPI路由问题
  • .net中MVC web项目和webapi有啥区别?
  • asp.net MVC api 如何同时支持POST和GET
  • WEBapi如何 去除 ASP.NET_SessionId 这个返回的Coo...
  • 网站首页网页制作脚本下载服务器操作系统网站运营平面设计媒体动画电脑基础硬件教程网络安全基础应用实用技巧自学过程首页asp.net浅谈asp.net core webapi几种版本控制对比xaml: 自定义控件中事件处理的最佳实践方法asp.net 下载文件时输出文件内容asp.net多彩下拉框开发实例asp.net 获取图片高度和宽度实例代码asp.net2.0 sql server数据库连接详解asp.net使用jquery模板引擎jtemplates呈现表格asp.net mvc开发之删除修改数据.net core 实现微信小程序支付功能(统一下单)asp.net 下载功能的解决方案asp.net文件处理如何操作未将对象引用设置到对象的实例 (java正则表达式 pattern和matcheasp.net(c#)网页跳转七种方法小结未能加载文件或程序集“xxx”或它asp.net“服务器应用程序不可用”asp.net中的几种弹出框提示基本实asp.net gridview 72般绝技asp.net生成excel并导出下载五种asp.net对路径"xxxxx"asp.net汉字转拼音和获取汉字首字手把手教你mvc导入excelasp.net网站首页根据ip自动跳转指定页面的asp.net小孔子cms中的数据添加修改mvc+bootstrap+drapper使用pagedlist.mvc提交页面的定位--scrollintoview的用法c#默认以管理员身份运行程序实现代码asp.net套用母版页后元素id不一致(个人总扩展asp.net mvc三层框架且使用structure浅析mvp模式中v-p交互问题及案例分享asp.net中sqlcachedependency缓存技术概述
    免责声明 - 关于我们 - 联系我们 - 广告联系 - 友情链接 - 帮助中心 - 频道导航
    Copyright © 2017 www.zgxue.com All Rights Reserved