使用Markdown來編寫API
Markdown是一種輕量級標記式語言，他具有輕量化、易讀易寫特性，並且對於圖片，圖表、數學式都有支援，它允許人們使用易讀易寫的純文字格式編寫文件，然後轉換成有效的XML或HTML。
API Blueprint是一種Markdown，針對API做了一些改變，也有很多工具支援，讓你極易產生API並且是開源的。
apiary https://apiary.io/
線上編輯，並渲染語法產生HTML，也可以下載
Aglio https://github.com/danielgtaylor/aglio
本地端渲染HTML支援自己設計Theme
pmtoapib https://github.com/PhillippOhlandt/pmtoapib
把你的postman轉換為API Blueprint文檔
還有許多工具詳細可以看工具連結
我們現在來說明如何使用Aglio。
先下載GIT
git clone https://github.com/danielgtaylor/aglio.git
他有兩種方式，直接安裝npm install –save aglio需要NodeJs，如果你沒有NodeJs，建議使用docker。
-i /tmp/你的apib -o /tmp/你輸出的檔案
docker run -v $(pwd):/tmp -t aglio -i /tmp/input.apib -o /tmp/output.html
這可以直接把你的API Blueprint轉換為HTML靜態檔案
當你很多檔案需要輸出時，可以寫一個shell檔來執行
#!/bin/bash docker run -v $(pwd):/tmp -t aglio -i /tmp/input.apib -o /tmp/output.html exit docker run -v $(pwd):/tmp -t aglio -i /tmp/input1.apib -o /tmp/output2.html exit docker run -v $(pwd):/tmp -t aglio -i /tmp/input3.apib -o /tmp/output3.html exit
當然以也可以改變輸出的樣式
docker run -v $(pwd):/tmp -t aglio --theme-variables /path/to/my-colors.less -i /tmp/input.apib -o /tmp/output.html
根據此範例設置你的less
https://github.com/danielgtaylor/aglio/blob/olio-theme/styles/variables-default.less
到這裡你已經可以快速產出文件，易讀的文件，由於Markdown非常容易閱讀，之後的維護也不須太多的成本。
在介紹一個實用的工具pmtoapib
他用於將Postman轉換為API Blueprint，讓你輕鬆轉換。
一樣先下載git
git clone https://github.com/PhillippOhlandt/pmtoapib.git
由於他是用go編寫的，我們直接使用docker
docker run --rm -it -v "$PWD:/opt" phillippohlandt/pmtoapib -collection collection.json -destination docs
Postman json 檔可至Postman 對著你的Collections右鍵Export請選擇2.0
文章參考
https://zh.wikipedia.org/wiki/Markdown
https://github.com/danielgtaylor/aglio
以上本篇就是使用Markdown來編寫API的介紹呦！喜歡歐斯瑞的讀者們，別忘了追蹤我們的Facebook粉絲團及IG，還有電子報，就不會錯過關於歐斯瑞的最新消息及文章分享呦！有任何問題，也歡迎隨時聯繫我們！
我要留言