手把手教你AspNetCore WebApi：Swagger（Api文檔）

前言

小明已經實現「待辦事項」的增刪改查，並美滋滋向負責前端的小紅介紹Api接口，小紅很忙，暫時沒有時間聽小明介紹，但願小明能給個Api文檔。對於碼農小明來講能不寫文檔就儘可能不要寫，不過這也難不倒小明，他知道Swagger不只能夠自動生成Api文檔，並還能夠用Swagger進行接口測試。

Swagger是什麼？

Swagger用於描述 REST API。 它容許計算機和人員瞭解服務的功能，而無需直接訪問實現（源代碼、網絡訪問、文檔）。

包安裝

• 右鍵單擊「解決方案資源管理器」 > 「管理 NuGet 包」中的項目
• 將「包源」設置爲「nuget.org」
• 確保啓用「包括預發行版」選項
• 在搜索框中輸入「Swashbuckle.AspNetCore」
• 從「瀏覽」選項卡中選擇最新的「Swashbuckle.AspNetCore」包，而後單擊「安裝」

添加Swagger生成器

將Swagger生成器添加到 Startup.ConfigureServices 方法中的服務集合中：

services.AddSwaggerGen();

配置Swagger中間件

在 Startup.Configure 方法中，啓用中間件爲生成的 JSON 文檔和 Swagger UI 提供服務：

app.UseSwagger();
app.UseSwaggerUI(c =>
{
    c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
});

XML註釋

• 在「解決方案資源管理器」中右鍵單擊該項目，而後選擇「編輯<project_name>.csproj」 。

• 手動將PropertyGroup添加：

  true

更改services.AddSwaggerGen();代碼以下：

services.AddSwaggerGen((c =>
{
    var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
    var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
    c.IncludeXmlComments(xmlPath);
}));

效果

小結

目前爲止，小明終於把API文檔也搞定了，摸了摸光滑的腦殼，小明美滋滋把API地址給小紅髮去，心想這樣小紅確定很滿意了吧，但對不能與小紅面對面的交流接口也有一絲絲淡淡的失望。