如何在ASP.NET中利用WebApi实现一个版本控制功能

本篇文章为大家展示了如何在ASP.NET中利用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());      }    });    //……    }}

上述内容就是如何在ASP.NET中利用WebApi实现一个版本控制功能，你们学到知识或技能了吗？如果还想学到更多技能或者丰富自己的知识储备，欢迎关注编程网行业资讯频道。