最近更新: 2014-07-16

我對 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 複雜了。