API Blueprint - 建立 API 文件的好工具

一直以來都在找一套可以方便快速地建立 API 文件的工具，對於這個工具，個人覺得需要符合以下幾個要求

• 觀閱文件的人不用安裝軟體，所以最好能夠產出 PDF 或 HTML 這類靜態文件
• 文件內容需要乾淨清楚，不用太複雜的附加功能
• 可以快速跳到某個 API 的內容
• 可以直接透過打字的方式建立文件，不用滑鼠拉來拉去，最好就是 RAML 這類通用的格式
• 對於 API 中傳遞的參數或資料結構能 Highlight 標示出來

看起來沒有很奇怪的要求，但就是找不到一個符合的工具。

今天剛好看到有個叫做 API Blueprint 的東西，就來試試看吧
API Blueprint - https://apiblueprint.org/

API Blueprint 算是一種專門用來描述 API 的檔案格式。
文件的寫法是使用 Markdown，標準的副檔名是 apib。

雖然是 Markdown 格式，但 API Blueprint 還是對不同的 tag 有自己的解釋。
所以需要有 Editor 跟 Viewer 來搭配。

Editor - API Blueprint Grammar for Atom

從 API Blueprint 的網站看到 sublime text 跟 atom 都有 plug-in 可以用， 如果不想用 Plug-in 的話，也可以試試把 Code Style 調成 Markdown 也是可以。

apm install language-api-blueprint

Preview - API Blueprint Preview

可以邊編輯 apib 時，馬上預覽文件的結果。
這個 plug-in 需要 aglio 套件，而 aglio 是用 node.js ，所以還必須先安裝 node.js

sudo npm install -g aglio

安裝 aglio 後再安裝 plug-in

apm install api-blueprint-preview

產生 API 文件

apib 文件編輯完成後，當然是產出 API 文件囉！
把 API 文件轉出成 HTML 可以讓其它需要觀閱的人不用安裝軟體就能直接開啓。

要轉成 HTML 文件，其實不用再安裝其它套件了，因為剛剛安裝好的 aglio 就可以做到了。

簡單透過下面的指令就完成了。

aglio -i service.apib -o api.html