API Blueprint

對 API 文檔的幻想

你對 API 文檔有哪些需求？寫起來方便看起來舒服？

這兩個應該是文檔最基本的需求了。

其實，先後端配合開發的時候，還經常會有這樣一種需求：

「你接口定義好了嗎？定義好了的話能不能先幫我作一個 Mock Server 讓我先跑起來？」

  

apiary

曾經和前端同事合做開發的時候，就意外發現了這樣一個網站。

在上面能夠用 Markdown 的語法寫文檔，只要用統一的格式邊寫，它就能自動生成漂亮的展現頁面和 Mock Server。

網站作的很是好，免費版能夠供小團隊使用。

最近發現，這家公司把它們的這套 API 標準開源了，還有對應的 Parser，Renderer，Mock Server，Editor等等。配套設施很是全，徹底能夠本身搭一個了。

相關標準和工具在這裏：https://apiblueprint.org/

  

編輯器

編輯器其實很是簡單，由於是基於 Markdown 的，因此若是你的編輯器支持 Markdown 語法高亮就好了，總之就是你愛用什麼就用什麼。

可是社區也有人作了一些插件，例如 api-blueprint-preview 就能夠更方便地預覽最終效果，還有這個插件 linter-api-blueprint 能夠檢查語法錯誤。

Atom 下插件最多，總之編輯器徹底不是個問題。

API Blueprint 有本身的後綴名：apib，並且 github 能夠識別它！

  

Renderer

Renderer 是什麼呢？它主要負責把你用 Markdown 寫的文檔渲染成靜態 HTML 頁面。

這裏介紹一下：aglio

安裝起來很是簡單：

npm install -g aglio

用起來也一樣簡單：

aglio -i document.apib --theme-template triple -o output.html

最終效果：

它能夠多種模板，也能夠自定義樣式，更多需求能夠看它的文檔。

  

Mock Server

Mock Server 就要靠另外一個工具了：drakov

安裝起來一樣很簡單：

npm install -g drakov

而後跑起來：

drakov -f "*.md"

你會看到以下信息：

而後直接去瀏覽器中訪問便可。

 

自動化

相關工具都搞定了，還缺什麼呢？主要就差自動化部署了，每次人肉重啓是不可能的。

但這塊沒有現成的工具，或者說這塊能夠和現有的不少工具配合，例如配合 Jenkins 再寫點腳本，很快就能實現了。

 

源地址:http://www.dozer.cc/2016/01/api-blueprin...