ASP.NET Core 3.0 實戰:構建多版本 API 接口
阿新 • • 發佈:2019-01-05
版本信息 include swaggerui 各類 val 業務 oca head sem 第一次在博客寫分享,請多多捧場,如有歧義請多多包含!
因為業務需求發展需要,所以API接口的變更升級是必不可少的事情,而原有的接口是不可能馬上停止使用的。例如:Login接口為例,1.0版本之返回用戶的基本信息,而2.0版本的叠代下,要把用戶祖宗十八代信息都要返回到客戶端,這時候1.0 vs 2.0版本的返回信息有一點信息上的差異,如果在不進行版本控制的情況下,在原1.0的版本下優化,那麽會出現一個比較嚴重的問題,如果還有在使用原1.0版本的終端豈不是GG了,所以如何能魚與熊掌兼得,同時為1.0、2.0版本的終端考慮,所以一般常見的幾種解決方案如下:
1、使用不同API名稱(常見同時最為惡心)
這種是非常簡單粗暴,非靈活處理方案,例如:1.0=Login 2.0=NewLogin 相對於來說是可以有效兼顧到各版本的終端用戶,但是還是不夠靈活,可配置度有點低。
1.0版本 https://****.com/Login
2.0版本 https://****.com/NewLogin
2、請求時帶參數(這裏就不詳細說了)
1.0版本 https://****.com/Login?version=1
2.0版本 https://****.com/Login?version=1
3、Header中標識版本信息
終端調用API接口時,在Header中添加參數來表明請求的版本信息
4、在URL中標識版本信息
1.0版本 https://****.com/v1/Login
2.0版本 https://****.com/v2/Login
這裏主要介紹的是第四種方案的項目搭建(網上有很多類似的文章描述)
1、建立web api項目
2、NuGet集成以下組件
SwashBuckle.AspNetCore 4.0.1
Microsoft.AspNetCore.Mvc.Versioning 3.1.1
Microsoft.AspNetCore.Mvc.Versioning.ApiExplorer 3.1.0
Microsoft.Extensions.PlatformAbstractions1.1.0 (選擇性集成,如果不需要API XMl文檔生成的可以去除)
以上組件的描述、作用請各位google、baidu下去了解,這裏不詳細說明了
3、項目、代碼上的設置/改動
在Startup->ConfigureServices方法中添加以下代碼
services.AddApiVersioning((o) => { o.ReportApiVersions= true;//可選配置,設置為true時,header返回版本信息 o.DefaultApiVersion = new ApiVersion(1, 0);//默認版本,請求未指明版本的求默認認執行版本1.0的API o.AssumeDefaultVersionWhenUnspecified = true;//是否啟用未指明版本API,指向默認版本 }).AddVersionedApiExplorer(option => { option.GroupNameFormat= "‘v‘VVVV";//api組名格式 option.AssumeDefaultVersionWhenUnspecified = true;//是否提供API版本服務 }).AddSwaggerGen((s) => { //填充UI內容 var provider = services.BuildServiceProvider().GetRequiredService<IApiVersionDescriptionProvider>(); foreach (var description in provider.ApiVersionDescriptions) { s.SwaggerDoc(description.GroupName, new Info() { Title = $"體檢微服務接口 v{description.ApiVersion}", Version = description.ApiVersion.ToString(), Description = "微服務框架-切換版本請點右上角版本切換", Contact = new Contact() { Name = "榮少(黎更榮) WeChat:186***** QQ:157537648", Email = "*******@hotmail.com" } } ); } //生成API XML文檔 var basePath = PlatformServices.Default.Application.ApplicationBasePath; var xmlPath = Path.Combine(basePath, typeof(Startup).GetTypeInfo().Assembly.GetName().Name + ".xml"); s.IncludeXmlComments(xmlPath); });
以上代碼其中option.GroupNameFormat = "‘v‘VVVV";//api組名格式,各位可以嘗試玩玩~~~~
在Startup->Configure方法中添加以下代碼
app.UseSwagger().UseSwaggerUI((o) => { foreach (var description in provider.ApiVersionDescriptions) { o.SwaggerEndpoint($"/swagger/{description.GroupName}/swagger.json", description.GroupName.ToUpperInvariant()); } });
其中在Startup->Configure方法中缺少了IApiVersionDescriptionProvider provider參數,自己手動補上即可
//項目自動生成的版本 public void Configure(IApplicationBuilder app, IHostingEnvironment env) //參數補上後的版本 public void Configure(IApplicationBuilder app, IHostingEnvironment env, IApiVersionDescriptionProvider provider)
以上配置基本上算時完成了,那麽Web Api要怎麽寫法呢?
在WebApi項目中Controllers下建立v1、v2倆個文件夾
namespace WebApplication1.Controllers.v1 { [ApiVersion("1.0")] [Route("api/v{version:apiVersion}/[controller]")] [ApiController] public class ValuesController : ControllerBase { [HttpGet] public ActionResult<IEnumerable<string>> Get() { return new string[] { "v1", "v1" }; } } }
namespace WebApplication1.Controllers.v2 { [ApiVersion("2.0")] [Route("api/v{version:apiVersion}/[controller]")] [ApiController] public class ValuesController : ControllerBase { [HttpGet] public ActionResult<IEnumerable<string>> Get() { return new string[] { "v2", "v2" }; } } }
這裏的路由設置了配置的標簽{version:apiVersion},其中ApiVersion中有各類的屬性字段,例如:棄用(不代表停用,就好像巨硬上已經過時的方法)該版本API-ApiVersion("1.0", Deprecated = true)],該[ApiVersionNeutral
]標簽就是表明停用,不需要該版本。
配置完成後,可以直接用url訪問不同版本的接口地址:
https://localhost:44383/api/v1/Values
https://localhost:44383/api/v2/Values
最後的配置,因為項目默認啟動的是api/Values接口地址,需要修改項目Properties->launchSettings.json
最終運行效果如下:
如果是對您有幫助,而您又比較慷概的請微信打賞下(後續回有更多的分享):
ASP.NET Core 3.0 實戰:構建多版本 API 接口