.NetCore使用Swagger+API多版本控制
本文例項環境及版本.NetCore3.1、Swagger6.1
現在的開發大部分都是前後端分離的模式了，後端提供介面，前端呼叫介面。後端提供了介面，需要對介面進行測試，之前都是使用瀏覽器開發者工具，或者寫單元測試，再或者直接使用Postman，但是現在這些都已經out了。後端提供了介面，如何跟前端配合說明介面的性質，引數等這也是一個問題。有沒有一種工具可以根據後端的介面自動生成介面文件，說明介面的性質，引數等資訊，又能提供介面呼叫等相關功能呢？答案是有的。Swagger 是一個規範和完整的框架，用於生成、描述、呼叫和視覺化 RESTful 風格的 Web 服務。而作為.net core開發，Swashbuckle是swagger應用的首選！
總體目標是使客戶端和檔案系統作為伺服器以同樣的速度來更新。檔案的方法、引數和模型緊密整合到伺服器端的程式碼，允許 API 來始終保持同步。Swagger 讓部署管理和使用功能強大的 API 從未如此簡單。
Swashbuckle.AspNetCore原始碼地址：https://github.com/domaindrivendev/Swashbuckle.AspNetCore
整個swagger頁面訪問流程如下：
1、瀏覽器輸入swaggerUI頁面地址，比如：http://localhost:5000/swagger/index.html，這個地址是可配置的
2、請求被SwaggerUI中介軟體攔截，然後返回頁面，這個頁面是嵌入的資原始檔，也可以設定成外部自己的頁面檔案（使用外部靜態檔案攔截）
3、頁面接收到Swagger的Index頁面後，會根據SwaggerUI中介軟體中使用SwaggerEndpoint方法設定的文件列表，載入第一個文件，也就是獲取文件架構資訊swagger.json
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(basePath, 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.SubstituteApiVersionInUrl = 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 = "標題", Email = "", 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}引數。
//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/javascript'>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
世界再大也有盡頭！