別用 RAML 撰寫你的 API 文件,千萬不要。

這篇文章專門講解我如何RAML 騙到入坑然後放棄的過程。最近在找 API 文件工具,然後就剛好看見了 RAMLRAML 是一個撰寫 API 文件的格式,風格是延續 YAML 的。

現在讓我們看看官方網站的示意圖,你會發現:「哇,這根本夭壽棒啊!」。

所以我才被騙進來了,不是嗎?如果你現在打算用 RAML,請留步

撰寫風格一般

這不是我覺得被騙的主因,但是撰寫風格是 YAML,雖然比起 JSON 已經好上許多了,但是因為在 RAML 裡面常常會用到 !include 來引用另一個 RAML 檔案,令人感到有點聒噪

/authorization:
  displayName: Authorization
  description: Operations about the authorization.

  post:
    description: Generate an authorization token.
    responses: !include responses/post_authorization.raml
    body: !include bodies/post_authorization.raml

  delete:
    description: Destroy the authorization token.
    securedBy: [JWT, FormValidation]
    responses: !include responses/delete_authorization.raml

沒有教學、文件太死板

RAML 的官方網站看起來是很棒沒錯,他們盡可能地告訴你 RAML 支援什麼功能,但實際上卻沒有任何教學教導你學會怎麼使用,取而代之的是一長串的功能文件,這就像是你要寫 HTML5,直接丟給你一個 W3C 文稿一樣閱讀會有障礙

社區緩慢、根本沒工具

在我歡欣鼓舞之際,我發現根本沒有工具可以替我的 RAML 產生出 API 網頁。沒錯,你寫了一個 API 文件但是根本沒辦法轉換成網頁或是 Markdown 格式的時候,這個 API 文件跟報廢沒有兩樣

其實是有工具的,但是因為 RAML 有分兩個版本:0.81.0 導致分歧嚴重,基於 0.8 有太多在 1.0 被棄用的標準,我決定直接使用已經出來半年之久的 1.0,結果現在要生成網頁檔案的時候,我發現所有的工具仍都停留在 0.8,這讓我感覺好像笨蛋一樣。

我在這裡感受到一個點,由於其中的差異過大,然後加上 RAML 的支持者貌似不多,所以社區進步緩慢,導致沒有相關工具可以應對

沒有良好的介面

RAML2HTML 是一個 RAML 生成 HTML 網頁的工具,當然目前也僅支持 0.8 版本而且這幾乎是 RAML 唯一的一個網頁生成工具

這個網頁並不是設計的很詳細,而且不支援響應式設計,這表示著你在手機上並沒有辦法正常地瀏覽這個網頁,而且網頁設計是採用 Bootstrap 3 的燈箱特效,這也意味著當你要觀看 API 詳細使用方法時,你需要先等待那緩慢的燈箱特效結束才能夠繼續進行動作。

不易除錯

當你的 RAML 文件有錯時,而且你又剛好使用了 !include 來進行多重引用,你就會意識到 RAML 的除錯訊息會讓你不清不楚根本不讓你知道你的哪一個文件有問題,他只會告訴你像是 type is missed 這樣的簡單詞彙,所以你會需要自己用肉眼去更加仔細地除錯

時間流逝

花了大概兩個星期在 RAML 上,然後還要時不時地翻閱那十分死板的文件,然後又花上了我不少的時間在這篇文章上警告世人,你的時間很寶貴,還有,請珍惜生命

我想我之後應該會去投靠 API Blueprint 或是 Swagger 吧⋯⋯至少社群跟工具還有相關的整合性都比起 RAML 還要來得更好、更廣。