在前后端分離的大環境下，API接口文檔成為了前后端交流的一個重點。Swagger讓開發人員擺脫了寫接口文檔的痛苦。
官方網址：https://swagger.io/
在.Net Core WebApi中通過簡單配置即可使用這一強大的功能。
目錄：
.NetCore WebApi——基於JWT的簡單身份認證與授權（Swagger）
.NetCore WebApi —— Swagger版本控制
1.新建一個API的項目
選擇 API 項目
2.引入Swagger包。.Net Core 中支持兩個分別為Swashbuckle和NSwag。兩者的配置大同小異。這里以Swashbuckle為例。
方式1：選擇工具——Nuget包管理——管理解決方案的Nuget包
搜索：Swashbuckle.AspNetCore 安裝即可
方式2：直接在程序包管理控制台輸入：Install-Package Swashbuckle.AspNetCore 回車即可安裝
安裝之后在項目的Nuget包中就可以看到了
3.配置Swagger中間件
3.1 在Startup類ConfigureServices方法中添加Swagger服務並配置文檔信息
public void ConfigureServices(IServiceCollection services)
{
// 注冊Swagger服務
services.AddSwaggerGen(c =>
{
// 添加文檔信息
c.SwaggerDoc("v1", new Info { Title = "CoreWebApi", Version = "v1" });
});
services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_2);
}
3.2 在 Startup類Configure 方法中，啟用中間件為生成的 JSON 文檔和 Swagger UI 提供服務
public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
if (env.IsDevelopment())
{
app.UseDeveloperExceptionPage();
}
else
{
// The default HSTS value is 30 days. You may want to change this for production scenarios, see https://aka.ms/aspnetcore-hsts.
app.UseHsts();
}
app.UseHttpsRedirection();
// 啟用Swagger中間件
app.UseSwagger();
// 配置SwaggerUI
app.UseSwaggerUI(c =>
{
c.SwaggerEndpoint("/swagger/v1/swagger.json", "CoreWebApi");
});
app.UseMvc();
}
右鍵項目屬性，將URL地址固定到某個端口
然后將啟動項設置為當前項目，然后啟動。
在根目錄目前是沒有東西的。下一步將在根目錄處使用SwaggerUI
將RoutePrefix屬性設置為空
app.UseHttpsRedirection();
// 啟用Swagger中間件
app.UseSwagger();
// 配置SwaggerUI
app.UseSwaggerUI(c =>
{
c.SwaggerEndpoint("/swagger/v1/swagger.json", "CoreWebApi");
c.RoutePrefix = string.Empty;
});
再次啟動項目，SwaggerUI文檔成功顯示出來。整體簡潔大方。
API的信息說明：傳遞給AddSwaggerGen（）的方法可配置一些API的信息說明以及作者信息等，來展示到UI頁面。修改AddSwaggerGen（）方法。
// 注冊Swagger服務
services.AddSwaggerGen(c =>
{
// 添加文檔信息
c.SwaggerDoc("v1", new Info
{
Title = "CoreWebApi",
Version = "v1",
Description="ASP.NET CORE WebApi",
Contact=new Contact
{
Name="Jee",
Email="princess@gmail.com"
}
});
});
展示對應的信息
4.啟用XML注釋。上邊的效果只有一個簡單說明，並沒有我們在后台寫的注釋。啟用XML注釋之后可以輕松映射到UI界面方便前端開發人員理解。
右鍵當前項目——編輯****.csproj 的文件 在PropertyGroup標簽組中添加如下兩條
<GenerateDocumentationFile>true</GenerateDocumentationFile><NoWarn>$(NoWarn);1591</NoWarn>
這兩句的大概意思就是啟用XML注釋，並忽略未寫注釋的警告。不添加1591如果某個方法未寫 "///"各式的注釋，vs會有警示的消息。
之后AddSwaggerGen（）方法中讀取xml文件路徑並啟用
// 注冊Swagger服務
services.AddSwaggerGen(c =>
{
// 添加文檔信息
c.SwaggerDoc("v1", new Info
{
Title = "CoreWebApi",
Version = "v1",
Description="ASP.NET CORE WebApi",
Contact=new Contact
{
Name="Jee",
Email="princess@gmail.com"
}
});
// 使用反射獲取xml文件。並構造出文件的路徑
var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
// 啟用xml注釋. 該方法第二個參數啟用控制器的注釋，默認為false.
c.IncludeXmlComments(xmlPath,true);
});
再次啟動項目，可以看到寫的注釋全部都映射出來了
Text類的返回值也可以映射出來
Models文件夾中的實體也可以映射在接口下方
總結： 在.net core中配置swagger非常之快速。但這也是堪堪達到可以用的程度，算是入門級別吧。
源碼：GitHub
https://github.com/xiaoMaPrincess/Asp.NetCore-WebApi
多層架構版本：
https://github.com/xiaoMaPrincess/.NetCoreWebApi
原作者：千金不如一默