Swagger 初試筆記

一直以來，開發 WebAPI 我都很習慣用 工具 自動產生線上文件、線上測試介面以及客戶端程式庫，節省增刪介面方法後要同步調整文件及程式庫的工夫。

在 Swagger 流行之前，有好幾年的時間我都是靠土砲版 CodeGen 工具，用 Reflection 掃瞄 WebAPI 介面，從 XML Documentation 取得方法註解產生文件及客戶端元件。但土砲工具離要支援各式 WebAPI 應用仍有距離，功能完整性也待擴充。經過評估，回歸 Swagger 這類開放標準工具才是王道。

現在才入門已算晚，但好處是網路上已有許多前人整理的心得，以下是我的主要參考文件：

• mrkt 的程式學習筆記: ASP.NET Web API 文件產生器 - 使用 Swagger
• KingKong Bruce記事: ASP.NET Web API 文件產生器(2) - Swagger

已有現成文章參考，Swagger 概念與安裝、產生文件及線上測試介面的細節就不多說了，僅記錄我用它自動產生程式碼時遇到的幾個小問題：

1. 使用 Swashbuckle 5.6.0 版，GetXmlComentsPath() 傳回型別不再是 string，而是 Func ，與網站文章有點出入，要修改如下：

private static Func<XPathDocument> GetXmlCommentsPath()
{
	return () => new XPathDocument(HostingEnvironment.MapPath(@"~/App_Data/XmlDocument.xml"));
}

2. Swagger 只支援 ApiController，但大家都知道我是非 RESTful 陣營成員(參考： 閒聊 - Web API 是否一定要 RESTful? )，不以 HTTP 方法改用 Action 名稱區隔(術語為 RPC-style API)會導致一個 Controller 出現多個 Action 名稱不同但都是走 HttpPost 的方法，形成路由混淆，而檢視 Swagger UI 時也會出現錯誤： Not supported by Swagger 2.0: Multiple operations with path 'api/MyApiName' and method 'POST'. See the config setting - "ResolveConflictingActions" for a potential workaround ，解決方法是定義 "api///id" 路由，必要時可用 [ActionName("DoSomething")] 自訂名稱，或使用 [Route("api/MyApiName/DoSomething")] 定義路由。細節可參考官方文件： Routing in ASP.NET Web API Routing by Action Name 一節的說明。

3. Swashbuckle 會依據 WebAPI 介面自動產生 Swagger.json，下載位置在 httq://your-webapi-server/swagger/docs/v1，後續可用於程式碼產生。

4. Swagger Codegen 可依據 Swagger JSON 定義檔自動產生 Client 程式碼。 操作前先取得 Swagger CodeGen 程式：

   Invoke-WebRequest -OutFile swagger-codegen-cli.jar http://central.maven.org/maven2/io/swagger/swagger-codegen-cli/2.3.1/swagger-codegen-cli-2.3.1.jar

   再執行 swagger-codegen-cli.jar 傳入 Swagger.json 指定語言平台產生程式碼：

   java -jar .\\swagger-codegen-cli.jar generate -i http://localhost:25587/swagger/docs/v1 -l csharp -o E:\ApiClient

   -i 指定 Swagger.json 網址，-l 指定語言 csharp 可產生 C# 程式庫。Swagger CodeGen 支援 C#、C++、 Java 、Golang、 PHP 、Objective-C、 Perl 、PHP、PowerShell、 Python 、TypeScript/JavaScript 等各式呼叫端程式庫，我的土砲版只支援 C#，這也是吸引我改用 Swagger 的原因。

5. 用 VS2017 開啟 Swagger CodeGen 產生的 C# 專案，發現原本的 NuGet 參照有些問題，JsonSubTypes 及 RestSharp 參照有誤。專案原本 Target 是 .NET 4.5，實測升級到 4.5.2 可解決。

   

6. Swagger CodeGen 產生的 C# 客戶端專案還包含 NUnit 測試， 但我發現 NUnit NuGet 套件要升到 3.x，不然會出現 NUnit couldn't find any tests in IO.Swagger.dll 警示且無法測試。

   

   NUnit 要升級，但 RestSharp 升到 1.6 則會出現版本相容問題，如不想調程式留在 1.5.x 就好。

Some tips of using Swagger on ASP.NET MVC WebAPI.