aglio 基本教學

• Youtube Tutorial

相信大家在網路上一定都看過 API 文件，

那我們該如何撰寫 API 文件 給別人看呢 ？

今天我要教大家使用 aglio 來完成他 ！！

溫馨小提醒

之前也有介紹過利用 Swagger 建立 API 文件

django_rest_framework_swagger_tutorial

但今天的主角是 aglio

自由度更高！！

安裝 nodejs

請先確認自己的電腦有安裝 nodejs

安裝 aglio

請在你的命令提示字元 (cmd ) 底下輸入

使用 npm 安裝 aglio

npm install -g aglio

我們依照 DRF-dataTable-Example-server-side 這篇文章下去設計 API

Commandline executable

要將 .apib 邊譯為 .html , 可以執行

aglio -i index.apib -o index.html

那你現在一定在想，每次都要重新編譯超級麻煩 😠，但請不用擔心，

我們可以使用 Live-reloading preview server

( 也就是即時觀看，改什麼立即可以看到結果 )

aglio -i index.apib --server

接下來我們只需要去瀏覽 http://localhost:3000/ 就可以即時看到修改的內容。

注意

有時候在編譯，會提醒你錯誤，請把錯誤都修正，避免不必要的問題

為了方便維護 API 文件，我們可以使用 Including Files 的方法

<!-- include(filename.md) -->

更多用法可參考官方說明

https://github.com/danielgtaylor/aglio#installation--usage

依照 DRF-dataTable-Example-server-side 這篇文章下去設計 API

可以參考我的 index.html，直接用瀏覽器開啟即可 😄

畫面蠻漂亮的，也有很多種 theme 可以選擇

更多 theme 可以參考

https://github.com/danielgtaylor/aglio#example-output

由於之前介紹過 Swagger ，所以就用 aglio 和 Swagger 比較一下吧 !!

其實說穿了，還是要看自己的需求，如果需要自訂性比較高的，那一定就是選 aglio ;

相反的，假如需要可以直接測試且自動的幫你生成，就選 Swagger ( 自訂性較低 )。

所以說依照當下的需求下去選擇撰寫 API 文件 的工具絕對沒錯！！

• aglio