您好,登錄后才能下訂單哦!
這篇文章主要講解了“.NetCore使用Swagger+API多版本控制的流程是什么”,文中的講解內(nèi)容簡單清晰,易于學(xué)習(xí)與理解,下面請大家跟著小編的思路慢慢深入,一起來研究和學(xué)習(xí)“.NetCore使用Swagger+API多版本控制的流程是什么”吧!
本文實(shí)例環(huán)境及版本.NetCore3.1、Swagger6.1
現(xiàn)在的開發(fā)大部分都是前后端分離的模式了,后端提供接口,前端調(diào)用接口。后端提供了接口,需要對接口進(jìn)行測試,之前都是使用瀏覽器開發(fā)者工具,或者寫單元測試,再或者直接使用Postman,但是現(xiàn)在這些都已經(jīng)out了。后端提供了接口,如何跟前端配合說明接口的性質(zhì),參數(shù)等這也是一個(gè)問題。有沒有一種工具可以根據(jù)后端的接口自動(dòng)生成接口文檔,說明接口的性質(zhì),參數(shù)等信息,又能提供接口調(diào)用等相關(guān)功能呢?答案是有的。Swagger 是一個(gè)規(guī)范和完整的框架,用于生成、描述、調(diào)用和可視化 RESTful 風(fēng)格的 Web 服務(wù)。而作為.net core開發(fā),Swashbuckle是swagger應(yīng)用的首選!
總體目標(biāo)是使客戶端和文件系統(tǒng)作為服務(wù)器以同樣的速度來更新。文件的方法、參數(shù)和模型緊密集成到服務(wù)器端的代碼,允許 API 來始終保持同步。Swagger 讓部署管理和使用功能強(qiáng)大的 API 從未如此簡單。
整個(gè)swagger頁面訪問流程如下:
1、瀏覽器輸入swaggerUI頁面地址,比如:http://localhost:5000/swagger/index.html,這個(gè)地址是可配置的
2、請求被SwaggerUI中間件攔截,然后返回頁面,這個(gè)頁面是嵌入的資源文件,也可以設(shè)置成外部自己的頁面文件(使用外部靜態(tài)文件攔截)
3、頁面接收到Swagger的Index頁面后,會(huì)根據(jù)SwaggerUI中間件中使用SwaggerEndpoint方法設(shè)置的文檔列表,加載第一個(gè)文檔,也就是獲取文檔架構(gòu)信息swagger.json
4、瀏覽器請求的swagger.json被Swagger中間件攔截,然后解析屬于請求文檔的所有接口,并最終返回一串json格式的數(shù)據(jù)
5、瀏覽器根據(jù)接收到的swagger,json數(shù)據(jù)呈現(xiàn)UI界面
1、新建NetCore項(xiàng)目,添加相關(guān)Controller并添加引用Swashbuckle.AspNetCore.Swagger
2、在Startup中添加配置
在ConfigureServices中注入Swashbuckle服務(wù)
services.AddSwaggerGen(c => { c.SwaggerDoc("V1", new OpenApiInfo { //版本 Version = "V1", //標(biāo)題 Title = $"接口文檔-NetCore3.1", //描述 Description = $"NetCore Http API v1", //聯(lián)系方式 Contact = new OpenApiContact { Name = "測試", Email = "", Url = new Uri("https://www.cnblogs.com/mzflog/") }, License = new OpenApiLicense { Name = "測試2", Url = new Uri("https://www.cnblogs.com/mzflog/") } }); // 加載XML注釋 c.IncludeXmlComments(XmlCommentsFilePath); });
新增XmlCommentsFilePath 屬性,此時(shí)需要引用Microsoft.Extensions.PlatformAbstractions
/// <summary> /// 獲取當(dāng)前項(xiàng)目名的XML文件 /// </summary> static string XmlCommentsFilePath { get { var basePath = PlatformServices.Default.Application.ApplicationBasePath; var fileName = typeof(Startup).GetTypeInfo().Assembly.GetName().Name + ".xml"; return Path.Combine(basePath, fileName); } }
在Configure中添加Swagger中間件UseSwagger,UseSwaggerUI
UseSwagger:添加Swagger中間件,主要用于攔截swagger.json請求,從而可以獲取返回所需的接口架構(gòu)信息
UseSwaggerUI:添加SwaggerUI中間件,主要用于攔截swagger/index.html頁面請求,返回頁面給前端
app.UseSwagger(); app.UseSwaggerUI(c => { c.SwaggerEndpoint($"/swagger/V1/swagger.json", $"NetCore V1"); //c.RoutePrefix = string.Empty; //如果是為空 訪問路徑就為 根域名/index.html,注意localhost:8001/swagger是訪問不到的 //路徑配置,設(shè)置為空,表示直接在根域名(localhost:8001)訪問該文件 c.RoutePrefix = "swagger"; // 如果你想換一個(gè)路徑,直接寫名字即可,比如直接寫c.RoutePrefix = "swagger"; 則訪問路徑為 根域名/swagger/index.html });
右鍵項(xiàng)目屬性在生成中添加XML
此時(shí)通過http://localhost:端口號(hào)/swagger即可訪問
版本控制的好處:
1、有助于及時(shí)推出功能, 而不會(huì)破壞現(xiàn)有系統(tǒng)。
2、它還可以幫助為選定的客戶提供額外的功能。
1、添加對Microsoft.AspNetCore.Mvc.Versioning和Microsoft.AspNetCore.Mvc.Versioning.ApiExplorer的引用,本文使用版本4.1.0
2、在ConfigureServices中
services.AddApiVersioning(option => { // 可選,為true時(shí)API返回支持的版本信息 option.ReportApiVersions = true; // 請求中未指定版本時(shí)默認(rèn)為1.0 option.DefaultApiVersion = new ApiVersion(1, 0); //版本號(hào)以什么形式,什么字段傳遞 option.ApiVersionReader = ApiVersionReader.Combine(new HeaderApiVersionReader("api-version")); // 在不提供版本號(hào)時(shí),默認(rèn)為1.0 如果不添加此配置,不提供版本號(hào)時(shí)會(huì)報(bào)錯(cuò)"message": "An API version is required, but was not specified." //option.AssumeDefaultVersionWhenUnspecified = true; //默認(rèn)以當(dāng)前最高版本進(jìn)行訪問 //option.ApiVersionSelector = new CurrentImplementationApiVersionSelector(option); }).AddVersionedApiExplorer(opt => { //以通知swagger替換控制器路由中的版本并配置api版本 opt.SubstituteApiVersionInUrl = true; // 版本名的格式:v+版本號(hào) opt.GroupNameFormat = "'v'VVV"; //是否提供API版本服務(wù) opt.AssumeDefaultVersionWhenUnspecified = true; });
//方式一 (不建議使用) 此種方式報(bào)警告:ASP0000 從應(yīng)用程序代碼調(diào)用“BuildServiceProvider”會(huì)導(dǎo)致創(chuàng)建單例服務(wù)的附加副本??紤]替代方案,例如將依賴注入服務(wù)作為“配置”的參數(shù) services.AddSwaggerGen(options => { // 解析IApiVersionDescriptionProvider服務(wù) var provider = services.BuildServiceProvider().GetRequiredService<IApiVersionDescriptionProvider>(); //為每個(gè)發(fā)現(xiàn)的API版本添加一個(gè)swagger文檔 可跳過不需要記錄的 foreach (var description in provider.ApiVersionDescriptions) { options.SwaggerDoc(description.GroupName, CreateInfoForApiVersion(description)); } //加載XML注釋 并啟用控制器的注釋信息默認(rèn)為false不啟用 options.IncludeXmlComments(XmlCommentsFilePath,true); }); //方式二 (建議使用) services.AddSwaggerGen(); //解決上面報(bào)ASP0000警告的方案 services.AddOptions<SwaggerGenOptions>() .Configure<IApiVersionDescriptionProvider>((options, service) => { options.ResolveConflictingActions(apiDescriptions => apiDescriptions.First()); // 添加文檔信息 foreach (var item in service.ApiVersionDescriptions) { options.SwaggerDoc(item.GroupName, CreateInfoForApiVersion(item)); } //給swagger添加過濾器 //options.OperationFilter<SwaggerParameterFilter>(); // 加載XML注釋 options.IncludeXmlComments(XmlCommentsFilePath, true); });
添加CreateInfoForApiVersion方法
static OpenApiInfo CreateInfoForApiVersion(ApiVersionDescription description) { var info = new OpenApiInfo() { //標(biāo)題 Title = $".NET Core API for 測試項(xiàng)目 {description.ApiVersion}", //當(dāng)前版本 Version = description.ApiVersion.ToString(), //文檔說明 Description = "api項(xiàng)目 當(dāng)前環(huán)境-" + EnvironmentName, //聯(lián)系方式 Contact = new OpenApiContact() { Name = "標(biāo)題", Email = "", Url = null }, TermsOfService = new Uri(""), //許可證 License = new OpenApiLicense() { Name = "文檔", Url = new Uri("") } }; //當(dāng)有棄用標(biāo)記時(shí)的提示信息 if (description.IsDeprecated) { info.Description += " - 此版本已放棄兼容"; } return info; }
3、在Configure中添加
IApiVersionDescriptionProvider:用于枚舉定義的API版本的API版本描述符提供程序
public void Configure(IApplicationBuilder app, IWebHostEnvironment env, IApiVersionDescriptionProvider provider)
//添加Swagger中間件,主要用于攔截swagger.json請求,從而可以獲取返回所需的接口架構(gòu)信息 app.UseSwagger(opt => { //路由模板,默認(rèn)值是/swagger/{documentName}/swagger.json,這個(gè)屬性很重要!而且這個(gè)屬性中必須包含{documentName}參數(shù)。 //opt.RouteTemplate= "/swagger/{documentName}/swagger.json"; // 表示按Swagger2.0格式序列化生成swagger.json,這個(gè)不推薦使用,盡可能的使用新版本的就可以了 //opt.SerializeAsV2 }); //添加SwaggerUI中間件,主要用于攔截swagger / index.html頁面請求,返回頁面給前端 app.UseSwaggerUI(options => { // 為每個(gè)版本創(chuàng)建一個(gè)JSON foreach (var description in provider.ApiVersionDescriptions) { //這個(gè)屬性是往SwaggerUI頁面head標(biāo)簽中添加我們自己的代碼,比如引入一些樣式文件,或者執(zhí)行自己的一些腳本代碼 //options.HeadContent += $"<script type='text/javascript'>alert('歡迎來到SwaggerUI頁面')</script>"; //展示默認(rèn)頭部顯示的下拉版本信息 //options.SwaggerEndpoint($"/swagger/{description.GroupName}/swagger.json", description.GroupName.ToUpperInvariant()); //自由指定頭部顯示的下拉版本內(nèi)容 options.SwaggerEndpoint($"/swagger/{description.GroupName}/swagger.json", "coreApi" + description.ApiVersion); //如果是為空 訪問路徑就為 根域名/index.html,注意localhost:8001/swagger是訪問不到的 //options.RoutePrefix = string.Empty; // 如果你想換一個(gè)路徑,直接寫名字即可,比如直接寫c.RoutePrefix = "swagger"; 則訪問路徑為 根域名/swagger/index.html options.RoutePrefix = "swagger"; } });
4、在api的Controller中添加版本
[ApiVersion("1.0", Deprecated = false)] //Deprecated是否棄用該版本 默認(rèn)為false不棄用。即使標(biāo)記了棄用此接口還是會(huì)顯示,只是做個(gè)提示此版本將會(huì)被棄用了。 [Route("api/[controller]")] [ApiController] //[ApiExplorerSettings(IgnoreApi = true)] 隱藏該接口Controller public class ValuesController : Controller [Obsolete] //棄用該Action方法 [ApiExplorerSettings(IgnoreApi = true)] //隱藏該Action方法 public IEnumerable<string> Get()
為體驗(yàn)版本控制在新建一個(gè)控制器并添加 [ApiVersion("2.0")]
此時(shí)訪問頁面,在右側(cè)的下拉框中可選擇不同的版本,會(huì)展示不同版本下的控制器。
感謝各位的閱讀,以上就是“.NetCore使用Swagger+API多版本控制的流程是什么”的內(nèi)容了,經(jīng)過本文的學(xué)習(xí)后,相信大家對.NetCore使用Swagger+API多版本控制的流程是什么這一問題有了更深刻的體會(huì),具體使用情況還需要大家實(shí)踐驗(yàn)證。這里是億速云,小編將為大家推送更多相關(guān)知識(shí)點(diǎn)的文章,歡迎關(guān)注!
免責(zé)聲明:本站發(fā)布的內(nèi)容(圖片、視頻和文字)以原創(chuàng)、轉(zhuǎn)載和分享為主,文章觀點(diǎn)不代表本網(wǎng)站立場,如果涉及侵權(quán)請聯(lián)系站長郵箱:is@yisu.com進(jìn)行舉報(bào),并提供相關(guān)證據(jù),一經(jīng)查實(shí),將立刻刪除涉嫌侵權(quán)內(nèi)容。