{"id":20619750,"url":"https://github.com/twtrubiks/aglio_tutorial","last_synced_at":"2025-03-06T20:14:11.981Z","repository":{"id":84518874,"uuid":"93754442","full_name":"twtrubiks/aglio_tutorial","owner":"twtrubiks","description":"aglio tutorial","archived":false,"fork":false,"pushed_at":"2017-06-08T15:41:18.000Z","size":11,"stargazers_count":4,"open_issues_count":0,"forks_count":4,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-01-17T05:09:09.486Z","etag":null,"topics":["aglio","api-documentation","tutorial"],"latest_commit_sha":null,"homepage":null,"language":"HTML","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/twtrubiks.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-06-08T13:46:34.000Z","updated_at":"2024-05-15T01:18:33.000Z","dependencies_parsed_at":null,"dependency_job_id":"a29b0e71-ac66-4a5b-84c2-337b46f7c9e5","html_url":"https://github.com/twtrubiks/aglio_tutorial","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/twtrubiks%2Faglio_tutorial","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/twtrubiks%2Faglio_tutorial/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/twtrubiks%2Faglio_tutorial/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/twtrubiks%2Faglio_tutorial/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/twtrubiks","download_url":"https://codeload.github.com/twtrubiks/aglio_tutorial/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":242277684,"owners_count":20101542,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aglio","api-documentation","tutorial"],"created_at":"2024-11-16T12:12:26.848Z","updated_at":"2025-03-06T20:14:11.960Z","avatar_url":"https://github.com/twtrubiks.png","language":"HTML","readme":"# aglio-tutorial\n\n aglio 基本教學\n\n* [Youtube Tutorial](https://youtu.be/93takOJoZkk)\n\n相信大家在網路上一定都看過 **API 文件**，\n\n那我們該如何撰寫 **API 文件** 給別人看呢 ？\n\n今天我要教大家使用  [aglio](https://github.com/danielgtaylor/aglio) 來完成他 ！！\n\n***溫馨小提醒***\n\n之前也有介紹過利用 Swagger 建立 **API 文件**\n\n[django_rest_framework_swagger_tutorial](https://github.com/twtrubiks/django_rest_framework_swagger_tutorial)\n\n但今天的主角是 [aglio](https://github.com/danielgtaylor/aglio)\n\n 自由度更高！！\n\n## 安裝環境\n\n***安裝 nodejs***\n\n請先確認自己的電腦有安裝 [nodejs](https://nodejs.org/en/)\n\n***安裝 aglio***\n\n請在你的命令提示字元 (cmd ) 底下輸入\n\n使用 npm 安裝  [aglio](https://github.com/danielgtaylor/aglio)\n\u003enpm install -g aglio\n\n## 教學\n\n我們依照 [DRF-dataTable-Example-server-side](https://github.com/twtrubiks/DRF-dataTable-Example-server-side) 這篇文章下去設計 API\n\nCommandline executable\n\n要將 **.apib** 邊譯為 **.html** , 可以執行\n\n```cmd\naglio -i index.apib -o index.html\n```\n\n那你現在一定在想，每次都要重新編譯超級麻煩 :angry:，但請不用擔心，\n\n我們可以使用 **Live-reloading preview server**\n\n( 也就是即時觀看，改什麼立即可以看到結果 )\n\n```cmd\naglio -i index.apib --server\n```\n\n![](http://i.imgur.com/9AyeIyS.png)\n\n接下來我們只需要去瀏覽 [http://localhost:3000/](http://localhost:3000/) 就可以即時看到修改的內容。\n\n***注意***\n\n有時候在編譯，會提醒你錯誤，請把錯誤都修正，避免不必要的問題\n\n## 其他功能介紹\n\n為了方便維護 API 文件，我們可以使用 **Including Files** 的方法\n\n```no-highlight\n\u003c!-- include(filename.md) --\u003e\n```\n\n更多用法可參考官方說明\n\n[https://github.com/danielgtaylor/aglio#installation--usage](https://github.com/danielgtaylor/aglio#installation--usage)\n\n## 執行畫面\n\n依照 [DRF-dataTable-Example-server-side](https://github.com/twtrubiks/DRF-dataTable-Example-server-side) 這篇文章下去設計 API\n\n可以參考我的 [index.html](https://github.com/twtrubiks/aglio_tutorial/blob/master/index.html)，直接用瀏覽器開啟即可 :smile:\n\n![](http://i.imgur.com/xOe8qsD.png)\n\n畫面蠻漂亮的，也有很多種 theme 可以選擇\n\n更多 theme 可以參考\n\n[https://github.com/danielgtaylor/aglio#example-output](https://github.com/danielgtaylor/aglio#example-output)\n\n## 結論\n\n由於之前介紹過 Swagger ，所以就用 [aglio](https://github.com/danielgtaylor/aglio) 和 Swagger 比較一下吧 !!\n\nAPI 文件  | 優點                  |  缺點\n--:      | ----------            | ----------\n Aglio   | 自訂性高且支援 Markdown | 不可以直接測試 API\n Swagger | 可以直接測試 API        | 自訂性較低\n\n其實說穿了，還是要看自己的需求，如果需要自訂性比較高的，那一定就是選 [aglio](https://github.com/danielgtaylor/aglio) ;\n\n相反的，假如需要可以直接測試且自動的幫你生成，就選 Swagger ( 自訂性較低 )。\n\n所以說依照當下的需求下去選擇撰寫 **API 文件** 的工具絕對沒錯！！\n\n## Reference\n\n* [aglio](https://github.com/danielgtaylor/aglio)\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftwtrubiks%2Faglio_tutorial","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftwtrubiks%2Faglio_tutorial","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftwtrubiks%2Faglio_tutorial/lists"}