.NetCore使用Swagger+API多版本控制的流程分析
目錄
- 一、Swagger基本使用
- 二、Swagger結合版本控制
本文例項環境及版本.NetCore3.1、Swagger6.1
現在的開發大部分都是前後端分離的模式了，後端提供介面，前端呼叫介面。後端提供了介面，需要對介面進行測試，之前都是使用瀏覽器開發者工具，或者寫單元測試，再或者直接使用Postman，但是現在這些都已經out了。後端提供了介面，如何跟前端配合說明介面的性質，引數等這也是一個問題。有沒有一種工具可以根據後端的介面自動生成介面文件，說明介面的性質，引數等資訊，又能提供介面呼叫等相關功能呢？答案是有的。Swagger 是一個規範和完整的框架，用於生成、描述、呼叫和視覺化 RESTful 風格的 Web 服務。而作為.net core開發，Swashbuckle是swagger應用的首選！
總體目標是使客戶端和檔案系統作為伺服器以同樣的速度來更新。檔案的方法、引數和模型緊密整合到伺服器端的程式碼，允許 API 來始終保持同步。Swagger 讓部署管理和使用功能強大的 API 從未如此簡單。
Swashbuckle.AspNetCore原始碼地址：https://.com/domaindrivendev/Swashbuckle.AspNetCore
整個swagger頁面訪問流程如下：
1、瀏覽器輸入swaggerUI頁面地址，比如：http://localhost:5000/swagger/index.html，這個地址是可配置的
2、請求被SwaggerUI中介軟體攔截，然後返回頁面，這個頁面是嵌入的資源文www.cppcns.com
3、頁面接收到Swagger的Index頁面後，會根據SwaggerUI中介軟體中使用SwaggerEndpoint方法設定的文件列表，載入第一個文件，也就是獲取文件架構資訊swagger.on
4、瀏覽器請求的swagger.json被Swagger中介軟體攔截，然後解析屬於請求文件的所有介面，並最終返回一串json格式的資料
5、瀏覽器根據接收到的swagger,json資料呈現UI介面
一、Swagger基本使用
1、新建NetCore專案，新增相關Controller並新增引用Swashbuckle.AspNetCore.Swagger
2、在Startup中新增配置
在ConfigureServices中注入Swashbuckle服務
services.AddSwaggerGen(c =>
{
c.SwaggerDoc("V1",new OpenApiInfo
{
//版本
Version = "V1",//標題
Title = $"介面文件-NetCore3.1",//描述
Description = $"NetCore Http API v1",//聯絡方式
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 屬性，此時需要引用Microsoft.Extensions.PlatformAbstractions
/// <summary>
/// 獲取當前專案名的XML檔案
/// </summary>
static string XmlCommentsFilePath
{
get
{
var basePath = PlatformServices.Default.Application.ApplicationBasePath;
var fileName = typeof(Startup).GetTypeInfo().Assembly.GetName().Name + ".xml";
return Path.Combine(bwww.cppcns.comasePath,fileName);
}
}
在Configure中新增Swagger中介軟體UseSwagger，UseSwaggerUI
UseSwagger：新增Swagger中介軟體，主要用於攔截swagger.json請求，從而可以獲取返回所需的介面架構資訊
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是訪問不到的
//路徑配置，設定為空，表示直接在根域名（localhost:8001）訪問該檔案
c.RoutePrefix = "swagger"; // 如果你想換一個路徑，直接寫名字即可，比如直接寫c.RoutePrefix = "swagger"; 則訪問路徑為 根域名/swagger/index.html
});
右鍵專案屬性在生成中新增XML
此時通過http://localhost:埠號/swagger即可訪問
二、Swagger結合版本控制
版本控制的好處：
1、有助於及時推出功能,而不會破壞現有系統。
2、它還可以幫助為選定的客戶提供額外的功能。
1、新增對Microsoft.AspNetCore.Mvc.Versioning和Microsoft.AspNetCore.Mvc.Versioning.ApiExplorer的引用，本文使用版本4.1.0
2、在ConfigureServices中
services.AddApiVersioning(option =>
{
// 可選，為true時API返回支援的版本資訊
option.ReportApiVersions = true;
// 請求中未指定版本時預設為1.0
option.DefaultApiVersion = new ApiVersion(1,0);
//版本號以什麼形式，什麼欄位傳遞
option.ApiVersionReader = ApiVersionReader.Combine(new HeaderApiVersionReader("api-version"));
// 在不提供版本號時，預設為1.0 如果不新增此配置，不提供版本號時會報錯"message": "An API version is required,but was not specified."
//option.AssumeDefaultVersionWhenUnspecified = true;
//預設以當前最高版本進行訪問
//option.ApiVersionSelector = new CurrentImplementationApiVersionSelector(option);
}).AddVersionedApiExplorer(opt =>
{
//以通知swagger替換控制器路由中的版本並配置api版本
opt.Subswww.cppcns.comtituteApiVersionInUrl = true;
// 版本名的格式：v+版本號
opt.GroupNameFormat = "'v'VVV";
//是否提供API版本服務
opt.AssumeDefaultVersionWhenUnspecified = true;
});
//方式一 （不建議使用） 此種方式報警告：ASP0000 從應用程式程式碼呼叫“BuildServiceProvider”會導致建立單例服務的附加副本。考慮替代方案，例如將依賴注入服務作為“配置”的引數
services.AddSwaggerGen(options =>
{
// 解析IApiVersionDescriptionProvider服務
var provider = services.BuildServiceProvider().GetRequiredService<IApiVersionDescriptionProvider>();
//為每個發現的API版本新增一個swagger文件 可跳過不需要記錄的
foreach (var description in provider.ApiVersionDescriptions)
{
options.SwaggerDoc(description.GroupName,CreateInfoForApiVersion(description));
}
//載入XML註釋 並啟用控制器的註釋資訊預設為false不啟用
options.IncludeXmlComments(XmlCommentsFilePath,true);
});
//方式二 （建議使用）
services.AddSwaggerGen();
//解決上面報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()
{
//標題
Title = $".NET Core API for 測試專案 {description.ApiVersion}",//當前版本
Version = description.ApiVersion.ToString(),//文件說明
Description = "api專案 當前環境-" + EnvironmentName,//聯絡方式
Contact = new OpenApiContact() { Name = "標題",Url = null },TermsOfService = new Uri(""),//許可證
License = new OpenApiLicense() { Name = "文件",Url = new Uri("") }
}; //當有棄用標記時的提示資訊
if (description.IsDeprecated)
{
info.Description += " - 此版本已放棄相容";
}
return info;
}
3、在Configure中新增
IApiVersionDescriptionProvider：用於列舉定義的API版本的API版本描述符提供程式
public void Configure(IApplicationBuilder app,IWebHostEnvironment env,IApiVersionDescriptionProvider provider)
//新增Swagger中介軟體，主要用於攔截swagger.json請求，從而可以獲取返回所需的介面架構資訊
app.UseSwagger(opt =>
{
//路由模板，預設值是/swagger/{documentName}/swagger.json，這個屬性很重要！而且這個屬性中必須包含{documentName}引數www.cppcns.com。
//opt.RouteTemplate= "/swagger/{documentName}/swagger.json";
// 表示按Swagger2.0格式序列化生成swagger.json，這個不推薦使用，儘可能的使用新版本的就可以了
//opt.SerializeAsV2
});
//新增SwaggerUI中介軟體，主要用於攔截swagger / index.html頁面請求，返回頁面給前端
app.UseSwaggerUI(options =>
{
// 為每個版本建立一個JSON
foreach (var description in provider.ApiVersionDescriptions)
{
//這個屬性是往SwaggerUI頁面head標籤中新增我們自己的程式碼，比如引入一些樣式檔案，或者執行自己的一些程式碼
//options.HeadContent += $"<script type='text/'>alert('歡迎來到SwaggerUI頁面')</script>";
//展示預設頭部顯示的下拉版本資訊
//options.SwaggerEndpoint($"/swagger/{description.GroupName}/swagger.json",description.GroupName.ToUpperInvariant());
//自由指定頭部顯示的下拉版本內容
options.SwaggerEndpoint($"/swagger/{description.GroupName}/swagger.json","coreApi" + description.ApiVersion);
//如果是為空 訪問路徑就為 根域名/index.html,注意localhost:8001/swagger是訪問不到的
//options.RoutePrefix = string.Empty;
// 如果你想換一個路徑，直接寫名字即可，比如直接寫c.RoutePrefix = "swagger"; 則訪問路徑為 根域名/swagger/index.html
options.RoutePrefix = "swagger";
}
});
4、在api的Controller中新增版本
[ApiVersion("1.0",Deprecated = false)] //Deprecated是否棄用該版本 預設為false不棄用。即使標記了棄用此介面還是會顯示，只是做個提示此版本將會被棄用了。
[Route("api/[controller]")]
[ApiController]
//[ApiExplorerSettings(IgnoreApi = true)] 隱藏該介面Controller
public class ValuesController : Controller [Obsolete] //棄用該Action方法 [ApiExplorerSettings(IgnoreApi = true)] //隱藏該Action方法 public IEnumerable<string> Get()
為體驗版本控制在新建一個控制器並新增 [ApiVersion("2.0")]
此時訪問頁面，在右側的下拉框中可選擇不同的版本，會展示不同版本下的控制器。
才疏學淺，相關文件等僅供自我總結，如有相關問題可留言交流謝謝。
原文地址：https://www.cnblogs.com/mzflog/p/14969620.html
世界再大也有盡頭！
到此這篇關於.NetCore使用Swagger+API多版本控制的流程分析的文章就介紹到這了,更多相關.NetCore使用Swagger+API多版本控制內容請搜尋我們以前的文章或繼續瀏覽下面的相關文章希望大家以後多多支援我們！