ASP.NET Core WebApi使用Swagger生成api说明文档看这篇就够了
引言
在使用asp.net core 進行api開發完成后，書寫api說明文檔對于程序員來說想必是件很痛苦的事情吧，但文檔又必須寫，而且文檔的格式如果沒有具體要求的話，最終完成的文檔則完全取決于開發者的心情?；蛘咴敿汓c，或者簡單點。那么有沒有一種快速有效的方法來構建api說明文檔呢？答案是肯定的， Swagger就是最受歡迎的REST APIs文檔生成工具之一！
為什么使用Swagger作為REST APIs文檔生成工具
Swagger 可以生成一個具有互動性的API控制臺，開發者可以用來快速學習和嘗試API。
Swagger 可以生成客戶端SDK代碼用于各種不同的平臺上的實現。
Swagger 文件可以在許多不同的平臺上從代碼注釋中自動生成。
Swagger 有一個強大的社區，里面有許多強悍的貢獻者。
asp.net core中如何使用Swagger生成api說明文檔呢
Swashbuckle.AspNetCore 是一個開源項目，用于生成 ASP.NET Core Web API 的 Swagger 文檔。
NSwag 是另一個用于將 Swagger UI 或 ReDoc 集成到 ASP.NET Core Web API 中的開源項目。 它提供了為 API 生成 C# 和 TypeScript 客戶端代碼的方法。
下面以Swashbuckle.AspNetCore為例為大家進行展示
Swashbuckle由哪些組成部分呢？
Swashbuckle.AspNetCore.Swagger：將 SwaggerDocument 對象公開為 JSON 終結點的 Swagger 對象模型和中間件。
Swashbuckle.AspNetCore.SwaggerGen：從路由、控制器和模型直接生成 SwaggerDocument 對象的 Swagger 生成器。 它通常與 Swagger 終結點中間件結合，以自動公開 Swagger JSON。
Swashbuckle.AspNetCore.SwaggerUI：Swagger UI 工具的嵌入式版本。 它解釋 Swagger JSON 以構建描述 Web API 功能的可自定義的豐富體驗。 它包括針對公共方法的內置測試工具。
如何使用vs2017安裝Swashbuckle呢？
從“程序包管理器控制臺”窗口進行安裝
轉到“視圖” > “其他窗口” > “程序包管理器控制臺”
導航到包含 TodoApi.csproj 文件的目錄
請執行以下命令 ·Install-Package Swashbuckle.AspNetCore
從“管理 NuGet 程序包”對話框中：
右鍵單擊“解決方案資源管理器” > “管理 NuGet 包”中的項目
將“包源”設置為“nuget.org”
在搜索框中輸入“Swashbuckle.AspNetCore”
從“瀏覽”選項卡中選擇“Swashbuckle.AspNetCore”包，然后單擊“安裝”
添加并配置 Swagger 中間件
首先引入命名空間：
using Swashbuckle.AspNetCore.Swagger;將 Swagger 生成器添加到 Startup.ConfigureServices 方法中的服務集合中：
//注冊Swagger生成器，定義一個和多個Swagger 文檔services.AddSwaggerGen(c => { ? ? c.SwaggerDoc("v1", new Info { Title = "My API", Version = "v1" }); });在?Startup.Configure?方法中，啟用中間件為生成的 JSON 文檔和 Swagger UI 提供服務：
//啟用中間件服務生成Swagger作為JSON終結點app.UseSwagger();//啟用中間件服務對swagger-ui，指定Swagger JSON終結點app.UseSwaggerUI(c => { ? ?c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1"); });啟動應用，并導航到?http://localhost:<port>/swagger/v1/swagger.json。 生成的描述終結點的文檔顯示如下json格式。
可在?http://localhost:<port>/swagger?找到 Swagger UI。 通過 Swagger UI 瀏覽 API文檔，如下所示。
要在應用的根 (http://localhost:<port>/) 處提供 Swagger UI，請將?RoutePrefix?屬性設置為空字符串：
app.UseSwaggerUI(c => { ? ?c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1"); ? ?c.RoutePrefix = string.Empty; });Swagger的高級用法（自定義以及擴展）
使用Swagger為API文檔增加說明信息
在?AddSwaggerGen?方法的進行如下的配置操作會添加諸如作者、許可證和說明信息等：
//注冊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 顯示版本的信息如下圖所示：
為了防止博客被轉載后，不保留本文的鏈接，特意在此加入本文的鏈接：https://www.cnblogs.com/yilezhu/p/9241261.html
為接口方法添加注釋
大家先點擊下api，展開如下圖所示，可以沒有注釋啊，怎么來添加注釋呢？
按照下圖所示用三個/添加文檔注釋，如下所示
/// <summary>/// 這是一個api方法的注釋
/// </summary>
/// <returns></returns>
[HttpGet]
public ActionResult<IEnumerable<string>> Get() { ?
? return new string[] { "value1", "value2" }; }
然后運行項目，回到swaggerUI中去查看注釋是否出現了呢
還是沒有出現，別急，往下看！
啟用XML 注釋
可使用以下方法啟用 XML 注釋：
右鍵單擊“解決方案資源管理器”中的項目，然后選擇“屬性”
查看“生成”選項卡的“輸出”部分下的“XML 文檔文件”框
啟用 XML 注釋后會為未記錄的公共類型和成員提供調試信息。如果出現很多警告信息??例如，以下消息指示違反警告代碼 1591：
warning CS1591: Missing XML comment for publicly visible type or member 'TodoController.GetAll()'如果你有強迫癥，想取消警告怎么辦呢？可以按照下圖所示進行取消
注意上面生成的xml文檔文件的路徑，
?注意：
1.對于 Linux 或非 Windows 操作系統，文件名和路徑區分大小寫。?例如，“SwaggerDemo.xml”文件在 Windows 上有效，但在 CentOS 上無效。
2.獲取應用程序路徑，建議采用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設置xml文檔注釋路徑var basePath = Path.GetDirectoryName(typeof(Program).Assembly.Location);//獲取應用程序所在目錄（絕對，不受工作目錄影響，建議采用此方法獲取路徑）var xmlPath = Path.Combine(basePath, "SwaggerDemo.xml");c.IncludeXmlComments(xmlPath);});重新生成并運行項目查看一下注釋出現了沒有
通過上面的操作可以總結出，Swagger UI 顯示上述注釋代碼的?<summary>?元素的內部文本作為api大的注釋！
當然你還可以將?remarks?元素添加到?Get?操作方法文檔。?它可以補充?<summary>?元素中指定的信息，并提供更可靠的 Swagger UI。?<remarks>?元素內容可包含文本、JSON 或 XML。 代碼如下：
/// <summary>/// 這是一個帶參數的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}";}重新生成下項目，當好到SwaggerUI看到如下所示：
描述響應類型
摘錄自：https://www.cnblogs.com/yanbigfeg/p/9232844.html
接口使用者最關心的就是接口的返回內容和響應類型啦。下面展示一下201和400狀態碼的一個簡單例子：
我們需要在我們的方法上添加：[ProducesResponseType(201)][ProducesResponseType(400)]
然后添加相應的狀態說明：
最終代碼應該是這個樣子：
/// <summary>/// 這是一個帶參數的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調試下接口吧
點擊一個需要測試的API接口，然后點擊Parameters左右邊的“Try it out ” 按鈕
在出現的參數文本框中輸入參數，如下圖所示的，輸入參數2
點擊執行按鈕，會出現下面所示的格式化后的Response，如下圖所示
好了，今天的在ASP.NET Core WebApi使用Swagger生成api說明文檔看這篇就夠了的教程就到這里了。希望能夠對大家學習在ASP.NET Core中使用Swagger生成api文檔有所幫助！
總結
本文從手工書寫api文檔的痛處說起，進而引出Swagger這款自動生成api說明文檔的工具！然后通過通俗易懂的文字結合圖片為大家演示了如何在一個ASP.NET Core WebApi中使用SwaggerUI生成api說明文檔。最后又為大家介紹了一些ASP.NET Core 中Swagger的一些高級用法！希望對大家在ASP.NET Core中使用Swagger有所幫助！
原文地址：https://www.cnblogs.com/yilezhu/p/9241261.html
.NET社區新聞，深度好文，歡迎訪問公眾號文章匯總 http://www.csharpkit.com
總結
以上是生活随笔為你收集整理的ASP.NET Core WebApi使用Swagger生成api说明文档看这篇就够了的全部內容，希望文章能夠幫你解決所遇到的問題。
- 上一篇： COMCMS_CORE 起步篇，如何运行
- 下一篇： .NET Core微服务之基于Excep