ASP.NET Core WebApi版本控制的实现
这篇文章主要介绍了ASP.NET Core WebApi版本控制的实现,文中通过示例代码介绍的非常详细,对大家的学习或者工作具有一定的参考学习价值,需要的朋友们下面随着小编来一起学习学习吧
前言:
在日常项目开发中,随着项目需求不断的累加、不断的迭代;项目服务接口需要向下兼容历史版本;前些时候就因为Api接口为做版本管理导致接口对低版本兼容处理不友好。
最近就像了解下如何实现WebApi版本控制,那么版本控制有什么好处呢?
WebApi版本控制的好处
有助于及时推出功能, 而不会破坏现有系统,兼容性处理更友好。
它还可以帮助为选定的客户提供额外的功能。
接下来就来实现版本控制以及在Swagger UI中接入WebApi版本
一、WebApi版本控制实现
通过Microsoft.AspNetCore.Mvc.Versioning实现webapi 版本控制
创建WebApi项目,添加Nuget包:Microsoft.AspNetCore.Mvc.Versioning
1 | Install-Package Microsoft.AspNetCore.Mvc.Versioning |
修改项目Startup文件,使用Microsoft.AspNetCore.Mvc.Versioning
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 | 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),如下:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 | 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为固定格式
1 | [Route( "/api/v{version:apiVersion}/[controller]" )] |
调用方式:通过调用路径传入版本号,如:http://localhost:5000/api/v1/weatherforecast
c)通过Header头控制版本号:在Startup中设置(HeaderApiVersionReader、MediaTypeApiVersionReader)
1 2 3 | 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版本方法
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 | [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
1 2 3 4 | //swaggerui 包 Install-Package Swashbuckle.AspNetCore //api版本 Install-Package Microsoft.AspNetCore.Mvc.Versioning.ApiExplorer |
2、修改Startup代码:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 | 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、运行效果: