RAML vs API Blueprint

從 RAML 轉至 API Blueprint 之後發現兩個各有優劣之處,在這裡稍微敘述一下。

RAML

RAML 是最終被我唾棄的 API 文件撰寫風格,我很傷心我花了時間在這上面 :(。

優點

  • 功能性多、支援多種情況:能夠應付比較複雜的結構,如 HTTP 驗證等⋯的需求,且能夠有效地重複使用部分設置。
  • 檔案引用方便:你能夠把 API 文件拆開來,像是一個服務一個檔案,十分方便。

缺點

  • 沒有教學:比起教學來說,RAML 僅有像撰寫風範般的死板「文件」,你需要自己讀完整個文件才能理解如何使用 RAML。
  • 沒有社群支持、無工具:RAML 的社群十分狹窄,當要生成頁面文件時會找不到工具。
  • 格式過於聒噪:雖然撰寫風格類似 YAML,但還是有過多的符號需要讓你在鍵盤上多按個幾下。
  • 不易除錯:因為可以引用檔案,所以除錯時的錯誤訊息也就不可靠,不易找到錯誤點。

API Blueprint

API Blueprint 本身就有一個很適合企業來使用的官方網站,你能夠模擬伺服器,還有除錯,這更貼近了我的需求,且社群也較廣些。

優點

  • 有初階教學:官方有提供入門教學可讓初心者一步一步上手。
  • 以 Markdown 為標準:內容可以直接以 Markdown 風格撰寫。
  • 渲染主題美觀:渲染出來的頁面結果比起 RAML 要來的美觀與直覺,主題也更多。
  • 可讀性佳、不累贅:文件的撰寫方式是透過空白來進行排版,所以不會有太多的符號。
  • 官方工具較佳:官方就有提供一個十分適合企業用的開發網站
  • 方便除錯:由於不能引用檔案,錯誤訊息也就更直覺,更方便除錯。

缺點

  • 功能太過陽春:當你需要用到 HTTP 驗證或像是 JWT 時你就沒辦法了。
  • 常有重複內容:有些像是標頭的地方不能重複使用,你就需要複製貼上一次。
  • 無子母資源:當你的路由裡面有子路由的時候會不好歸類,你可能要將路由全部寫「平的」。
  • 標準不一:有些時候你需要用 Attributes,而有些時候你需要用 Parameters,不太好令人記住。
  • 需要額外方式避免錯誤:當你回傳的內容是空白時,你需要加一些額外詞彙讓解析時不會出錯,這應該是因為功能太過陽春還沒考慮到這種情況的關係。