转载

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 概念與安裝、產生文件及線上測試介面的細節就不多說了，僅記錄我用它自動產生程式碼時遇到的幾個小問題：

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

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

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 一節的說明。
Swashbuckle 會依據 WebAPI 介面自動產生 Swagger.json，下載位置在 httq://your-webapi-server/swagger/docs/v1，後續可用於程式碼產生。
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 的原因。
用 VS2017 開啟 Swagger CodeGen 產生的 C# 專案，發現原本的 NuGet 參照有些問題，JsonSubTypes 及 RestSharp 參照有誤。專案原本 Target 是 .NET 4.5，實測升級到 4.5.2 可解決。
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 就好。