我對 Swagger 的評價

我同事向我介紹了 Swagger (https://helloreverb.com/developers/swagger)。經過簡短評估後，我認為 Swagger 的想法不錯，但實務上是壞的。

Swagger 嘗試為 RESTful API 服務提供一個自我描述的方法並配合一個有用的客戶端工具，以便 RESTful API 的使用者了解服務內容與調用它。

還不錯，但不夠好。Swagger-ui 是和 Swagger 產生的自我描述文件內容綁定運行的客戶端工具。對於使用者來說，這是個容易使用的客戶端工具。但是有許多替代品。一個 IDE 也會提供更強大的 RESTful API 客戶端工具。 Swagger-ui 可能不是最好的，使用者更傾向使用自己偏好的工具。

壞。 Swagger 規範了一份 RESTful API 自我描述的文件格式。不同的程式語言需要實作各自的文件產生工具以輸出這份符合 swagger 規範的文件。 Restler 就是 PHP 語言的其中一個 swagger 框架。但是這些工具之間存在太多不同的標注方式與風格，不能提供 RESTful API 設計者一致的使用體驗。此外，其中一些工具過於侵入我既有的程式碼，甚至於可能要為了配合它而改變程式架構或類別繼承關係。沒有足夠的誘因讓我轉移程式碼。如果你是一個使用 Spring 框架的 Java 使用者，也許不會有轉移的問題。因為有一個 Spring 的擴充項目增加了 Swagger 用的 annotation ，可以在配合 Spring annotation 的情況下實現 Swagger 。

你設計的 RESTful API 需要一份清晰易讀的文件。但未必需要為此加入一個框架。一個可以從源碼註解區塊提取 RESTful API 說明內容，並將提取結果輸出為一份 HTML 文件的簡單工具，通常就足夠了。

樂多舊網址: http://blog.roodo.com/rocksaying/archives/29178954.html

樂多舊回應

cpckewang@gmail.com(kewang) (#comment-24932880)

Thu, 17 Jul 2014 10:51:36 +0800

我們公司內部最近開發新app的文件，主要是遵照 [API Blueprint](http://apiblueprint.org/) 這個規範來走，因為用Markdown來撰寫。

並且用下面兩套軟體來處理RESTful文件及Mock server的部分

* [Aglio](https://github.com/danielgtaylor/aglio)：這個是將用API Blueprint撰寫出來的Markdown文件，用比較漂亮的方式顯示出來
* [API-Mock](https://github.com/localmed/api-mock)：這個是把Markdown轉成Mock server，可以直接發request並傳回mock response，個人是覺得還不錯用。

未留名 (#comment-24932925)

Thu, 17 Jul 2014 11:32:15 +0800

我看了一下，API Blueprint 和 Swagger 的理念類似，都會產出一個規格化的 API 描述文件。
而 API Blueprint 可以直接輸出 HTML ，這點比 Swagger 好。

但是， Swagger 把 API 說明寫在程式碼中，並儘量依賴 reflect 技術探查函數內容，減少人工書寫部份。
而 API Blueprint 看來是把 API 說明另外寫在一份文件(用markdown 語法)。這一點 API Blueprint 輸。

我個人會把 API 說明寫在函數的 doc 區，再寫一個提取小程式把說明內容抓出來，然後交給 aglio 產生靜態的說明文件。
例如:
================
/**
# My API
## GET /message
+ Response 200 (text/plain)

Hello World!
*/
function get_message()
{
...
}
================

$ doc-extract my-service.js | aglio -i - -o my-service.html

PS. 我個人目前是用一般的 javadoc/phpdoc 語法在寫 API 說明，而我的提取工具會做一些簡單的意義轉換，例如把 @return 解釋為 response status code 。
同時，我的 container 工具會自動把名稱為 get/delete/put/post 的函數對應為 GET/DELETE/PUT/POST http method ，所以看函數名稱就可以知道 method ，不用特地寫出。

yurenju@gmail.com(Yuren Ju) (#comment-24933184)

Thu, 17 Jul 2014 14:37:59 +0800

RAML 呢？我覺得還蠻不錯的，不過還沒在實戰用過。
http://raml.org/

未留名 (#comment-24933248)

Thu, 17 Jul 2014 15:36:08 +0800

我覺得 RAML 複雜了。