引言
在使用asp.net core 進(jìn)行api開發(fā)完成后，書寫api說明文檔對于程序員來說想必是件很痛苦的事情吧八酒，但文檔又必須寫嫁怀，而且文檔的格式如果沒有具體要求的話，最終完成的文檔則完全取決于開發(fā)者的心情梗夸〔懔幔或者詳細(xì)點(diǎn)辛块，或者簡單點(diǎn)润绵。那么有沒有一種快速有效的方法來構(gòu)建api說明文檔呢尘盼？答案是肯定的配紫， Swagger就是最受歡迎的REST APIs文檔生成工具之一笨蚁！
為什么使用Swagger作為REST APIs文檔生成工具
- Swagger 可以生成一個具有互動性的API控制臺，開發(fā)者可以用來快速學(xué)習(xí)和嘗試API奋单。
- Swagger 可以生成客戶端SDK代碼用于各種不同的平臺上的實(shí)現(xiàn)览濒。
- Swagger 文件可以在許多不同的平臺上從代碼注釋中自動生成拖云。
- Swagger 有一個強(qiáng)大的社區(qū)宙项，里面有許多強(qiáng)悍的貢獻(xiàn)者尤筐。
asp.net core中如何使用Swagger生成api說明文檔呢
- Swashbuckle.AspNetCore 是一個開源項(xiàng)目，用于生成 ASP.NET Core Web API 的 Swagger 文檔掀淘。
- NSwag 是另一個用于將 Swagger UI 或 ReDoc 集成到 ASP.NET Core Web API 中的開源項(xiàng)目。 它提供了為 API 生成 C# 和 TypeScript 客戶端代碼的方法。
下面以Swashbuckle.AspNetCore為例為大家進(jìn)行展示
Swashbuckle由哪些組成部分呢架忌？
- Swashbuckle.AspNetCore.Swagger：將 SwaggerDocument 對象公開為 JSON 終結(jié)點(diǎn)的 Swagger 對象模型和中間件饰恕。
- Swashbuckle.AspNetCore.SwaggerGen：從路由、控制器和模型直接生成 SwaggerDocument 對象的 Swagger 生成器俱恶。 它通常與 Swagger 終結(jié)點(diǎn)中間件結(jié)合合是，以自動公開 Swagger JSON了罪。
- Swashbuckle.AspNetCore.SwaggerUI：Swagger UI 工具的嵌入式版本聪全。 它解釋 Swagger JSON 以構(gòu)建描述 Web API 功能的可自定義的豐富體驗(yàn)。 它包括針對公共方法的內(nèi)置測試工具难礼。
如何使用vs2017安裝Swashbuckle呢？
- 從“程序包管理器控制臺”窗口進(jìn)行安裝
- 轉(zhuǎn)到“視圖” > “其他窗口” > “程序包管理器控制臺”
- 導(dǎo)航到包含 TodoApi.csproj 文件的目錄
- 請執(zhí)行以下命令 ·Install-Package Swashbuckle.AspNetCore
- 1
- 從“管理 NuGet 程序包”對話框中：
- 右鍵單擊“解決方案資源管理器” > “管理 NuGet 包”中的項(xiàng)目
- 將“包源”設(shè)置為“nuget.org”
- 在搜索框中輸入“Swashbuckle.AspNetCore”
- 從“瀏覽”選項(xiàng)卡中選擇“Swashbuckle.AspNetCore”包蛾茉，然后單擊“安裝”
- 2
添加并配置 Swagger 中間件
首先引入命名空間：
using Swashbuckle.AspNetCore.Swagger;
將 Swagger 生成器添加到 Startup.ConfigureServices 方法中的服務(wù)集合中：
//注冊Swagger生成器，定義一個和多個Swagger 文檔
services.AddSwaggerGen(c =>
{
c.SwaggerDoc("v1", new Info { Title = "My API", Version = "v1" });
});
在 Startup.Configure 方法中谦炬，啟用中間件為生成的 JSON 文檔和 Swagger UI 提供服務(wù)：
//啟用中間件服務(wù)生成Swagger作為JSON終結(jié)點(diǎn)
app.UseSwagger();
//啟用中間件服務(wù)對swagger-ui吧寺，指定Swagger JSON終結(jié)點(diǎn)
app.UseSwaggerUI(c =>
{
c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
});
啟動應(yīng)用获搏，并導(dǎo)航到 http://localhost:<port>/swagger/v1/swagger.json赖条。 生成的描述終結(jié)點(diǎn)的文檔顯示如下json格式。
可在 http://localhost:<port>/swagger 找到 Swagger UI裸卫。 通過 Swagger UI 瀏覽 API文檔仿贬，如下所示。
要在應(yīng)用的根 (
http://localhost:<port>/) 處提供 Swagger UI墓贿，請將RoutePrefix屬性設(shè)置為空字符串：app.UseSwaggerUI(c => { c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1"); c.RoutePrefix = string.Empty; });
Swagger的高級用法（自定義以及擴(kuò)展）
使用Swagger為API文檔增加說明信息
在 AddSwaggerGen 方法的進(jìn)行如下的配置操作會添加諸如作者茧泪、許可證和說明信息等：
//注冊Swagger生成器蜓氨，定義一個和多個Swagger 文檔
services.AddSwaggerGen(c =>
{
c.SwaggerDoc("v1", new Info
{
Version = "v1",
Title = "yilezhu's API",
Description = "A simple example ASP.NET Core Web API",
TermsOfService = "None",
Contact = new Contact
{
Name = "依樂祝",
Email = string.Empty,
Url = "http://www.cnblogs.com/yilezhu/"
},
License = new License
{
Name = "許可證名字",
Url = "http://www.cnblogs.com/yilezhu/"
}
});
});
wagger UI 顯示版本的信息如下圖所示：
為了防止博客被轉(zhuǎn)載后，不保留本文的鏈接队伟，特意在此加入本文的鏈接：https://www.cnblogs.com/yilezhu/p/9241261.html
為接口方法添加注釋
大家先點(diǎn)擊下api穴吹，展開如下圖所示，可以沒有注釋啊嗜侮，怎么來添加注釋呢港令？
按照下圖所示用三個/添加文檔注釋，如下所示
/// <summary>
/// 這是一個api方法的注釋
/// </summary>
/// <returns></returns>
[HttpGet]
public ActionResult<IEnumerable<string>> Get()
{
return new string[] { "value1", "value2" };
}
然后運(yùn)行項(xiàng)目锈颗，回到swaggerUI中去查看注釋是否出現(xiàn)了呢
還是沒有出現(xiàn)顷霹，別急，往下看宜猜！
啟用XML 注釋
可使用以下方法啟用 XML 注釋：
- 右鍵單擊“解決方案資源管理器”中的項(xiàng)目泼返，然后選擇“屬性”
- 查看“生成”選項(xiàng)卡的“輸出”部分下的“XML 文檔文件”框
- 1530194540621
啟用 XML 注釋后會為未記錄的公共類型和成員提供調(diào)試信息。如果出現(xiàn)很多警告信息 例如姨拥，以下消息指示違反警告代碼 1591：
warning CS1591: Missing XML comment for publicly visible type or member 'TodoController.GetAll()'
如果你有強(qiáng)迫癥绅喉，想取消警告怎么辦呢？可以按照下圖所示進(jìn)行取消
注意上面生成的xml文檔文件的路徑叫乌，
注意：
? 1.對于 Linux 或非 Windows 操作系統(tǒng)柴罐，文件名和路徑區(qū)分大小寫。 例如憨奸，“SwaggerDemo.xml”文件在 Windows 上有效革屠，但在 CentOS 上無效。
? 2.獲取應(yīng)用程序路徑排宰，建議采用
Path.GetDirectoryName(typeof(Program).Assembly.Location)這種方式或者·AppContext.BaseDirectory這樣來獲取
//注冊Swagger生成器似芝，定義一個和多個Swagger 文檔
services.AddSwaggerGen(c =>
{
c.SwaggerDoc("v1", new Info
{
Version = "v1",
Title = "yilezhu's API",
Description = "A simple example ASP.NET Core Web API",
TermsOfService = "None",
Contact = new Contact
{
Name = "依樂祝",
Email = string.Empty,
Url = "http://www.cnblogs.com/yilezhu/"
},
License = new License
{
Name = "許可證名字",
Url = "http://www.cnblogs.com/yilezhu/"
}
});
// 為 Swagger JSON and UI設(shè)置xml文檔注釋路徑
var basePath = Path.GetDirectoryName(typeof(Program).Assembly.Location);//獲取應(yīng)用程序所在目錄（絕對，不受工作目錄影響板甘，建議采用此方法獲取路徑）
var xmlPath = Path.Combine(basePath, "SwaggerDemo.xml");
c.IncludeXmlComments(xmlPath);
});
重新生成并運(yùn)行項(xiàng)目查看一下注釋出現(xiàn)了沒有
通過上面的操作可以總結(jié)出党瓮，Swagger UI 顯示上述注釋代碼的 <summary> 元素的內(nèi)部文本作為api大的注釋！
當(dāng)然你還可以將 remarks 元素添加到 Get 操作方法文檔盐类。 它可以補(bǔ)充 <summary> 元素中指定的信息寞奸，并提供更可靠的 Swagger UI。 <remarks> 元素內(nèi)容可包含文本在跳、JSON 或 XML枪萄。 代碼如下：
/// <summary>
/// 這是一個帶參數(shù)的get請求
/// </summary>
/// <remarks>
/// 例子:
/// Get api/Values/1
/// </remarks>
/// <param name="id">主鍵</param>
/// <returns>測試字符串</returns>
[HttpGet("{id}")]
public ActionResult<string> Get(int id)
{
return $"你請求的 id 是 {id}";
}
重新生成下項(xiàng)目，當(dāng)好到SwaggerUI看到如下所示：
描述響應(yīng)類型
接口使用者最關(guān)心的就是接口的返回內(nèi)容和響應(yīng)類型啦猫妙。下面展示一下201和400狀態(tài)碼的一個簡單例子：
我們需要在我們的方法上添加：[ProducesResponseType(201)][ProducesResponseType(400)]
然后添加相應(yīng)的狀態(tài)說明：<response code="201">返回value字符串</response><response code="400">如果id為空</response>
最終代碼應(yīng)該是這個樣子：
/// <summary>
/// 這是一個帶參數(shù)的get請求
/// </summary>
/// <remarks>
/// 例子:
/// Get api/Values/1
/// </remarks>
/// <param name="id">主鍵</param>
/// <returns>測試字符串</returns>
/// <response code="201">返回value字符串</response>
/// <response code="400">如果id為空</response>
// GET api/values/2
[HttpGet("{id}")]
[ProducesResponseType(201)]
[ProducesResponseType(400)]
public ActionResult<string> Get(int id)
{
return $"你請求的 id 是 {id}";
}
效果如下所示
使用SwaggerUI測試api接口
下面我們通過一個小例子通過SwaggerUI調(diào)試下接口吧
- 點(diǎn)擊一個需要測試的API接口瓷翻，然后點(diǎn)擊Parameters左右邊的“Try it out ” 按鈕
- 在出現(xiàn)的參數(shù)文本框中輸入?yún)?shù)，如下圖所示的，輸入?yún)?shù)2
- 點(diǎn)擊執(zhí)行按鈕齐帚，會出現(xiàn)下面所示的格式化后的Response元践，如下圖所示
好了，今天的在ASP.NET Core WebApi使用Swagger生成api說明文檔看這篇就夠了的教程就到這里了童谒。希望能夠?qū)Υ蠹覍W(xué)習(xí)在ASP.NET Core中使用Swagger生成api文檔有所幫助单旁！
總結(jié)
? 本文從手工書寫api文檔的痛處說起，進(jìn)而引出Swagger這款自動生成api說明文檔的工具饥伊！然后通過通俗易懂的文字結(jié)合圖片為大家演示了如何在一個ASP.NET Core WebApi中使用SwaggerUI生成api說明文檔象浑。最后又為大家介紹了一些ASP.NET Core 中Swagger的一些高級用法！希望對大家在ASP.NET Core中使用Swagger有所幫助琅豆！
