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.0apiOtions.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.0apiOtions.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){//……//使用ApiVersioningapp.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、运行效果：　　