在前後端分離的大環境下，API接口文檔成爲了前後端交流的一個重點。Swagger讓開發人員擺脫了寫接口文檔的痛苦。
官方網址：https://swagger.io/
在.Net Core WebApi中通過簡單配置即可使用這一強大的功能。
目錄：
.NetCore WebApi——基於JWT的簡單身份認證與授權（Swagger）
.NetCore WebApi —— Swagger版本控制
選擇 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)
{
services.AddControllers();
//配置Mvc + json 序列化
services.AddMvc(options => { options.EnableEndpointRouting = false; }).SetCompatibilityVersion(CompatibilityVersion.Version_3_0).AddNewtonsoftJson(options =>
{
options.SerializerSettings.ReferenceLoopHandling = Newtonsoft.Json.ReferenceLoopHandling.Ignore;
options.SerializerSettings.DateFormatString = "yyyy-MM-dd HH:mm";
});
// 註冊Swagger服務
services.AddSwaggerGen(c =>
{
// 添加文檔信息
c.SwaggerDoc("v1", new Info { Title = "CoreWebApi", Version = "v1" });
// 使用反射獲取xml文件。並構造出文件的路徑
var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
// 啓用xml註釋. 該方法第二個參數啓用控制器的註釋，默認爲false.
c.IncludeXmlComments(xmlPath, true);
});
services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_3_0);
}
3.2 在 Startup類Configure 方法中，啓用中間件爲生成的 JSON 文檔和 Swagger UI 提供服務
public void Configure(IApplicationBuilder app, IWebHostEnvironment 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");
c.RoutePrefix = string.Empty;
});
app.UseMvc(routes =>
{
routes.MapRoute(
name: "default",
template: "{controller=Home}/{action=Index}/{id?}");
});
右鍵項目屬性，將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="[email protected]"
}
});
});
展示對應的信息
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="[email protected]"
}
});
// 使用反射獲取xml文件。並構造出文件的路徑
var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
// 啓用xml註釋. 該方法第二個參數啓用控制器的註釋，默認爲false.
c.IncludeXmlComments(xmlPath,true);
});
再次啓動項目，可以看到寫的註釋全部都映射出來了
Text類的返回值也可以映射出來
Models文件夾中的實體也可以映射在接口下方
