使用 API Blueprint 來編寫 API 接口文檔
- API Blueprint 是什么
- API Blueprint 語法高亮工具
- API Blueprint 渲染工具
API Blueprint 是什么
API Blueprint 用來編寫API文檔的一種標記語言，類似于Markdown，具體的語法規(guī)則可以在 API Blueprint documentation 查看，文檔里面還有一個簡短的 API Blueprint tutorial 建議先仔細閱讀一下這個教程。
使用 API Blueprint 文檔，配合一些開源的工具可以把接口文檔渲染成 html 再搭配一個靜態(tài)服務(wù)器，就可以很方便的共享給同事。
相對于 word 這種富文本格式的文檔來說，API Blueprint 是純文本，這樣可以很方便的使用版本控制工具 Git 來控制版本。
另外，配合一些工具，可以直接生成一個 mock data 數(shù)據(jù)，這樣只要和后端的同學約定好接口格式，那么前端再開發(fā)的時候可以使用 mock data 數(shù)據(jù)來做測試，等到后端寫好接口之后再做聯(lián)調(diào)就可以了。
API Blueprint 語法高亮工具
API Blueprint 社區(qū)提供了一些文本編輯器的插件，可以識別 API Blueprint 語法支持語法高亮。
API Blueprint 渲染工具
使用 apiblueprint 編寫好文檔使用，可以使用開源社區(qū)提供的一個工具 aglio 來把接口文檔渲染成 html 文件，aglio 還會啟動一個靜態(tài)服務(wù)器，這樣就可以在瀏覽器里面查看渲染好的文檔了。
aglio 的使用教程，可以直接查看官方開發(fā)倉庫的 readme 文檔。另外，這里也有一份資料 使用API-Blueprint 編寫 API 文檔可以參考。
