使用 API Blueprint 寫文件

Mon, 24 Apr 2023 17:50:21 +0800

API Blueprint 是一種 markdown 語法的擴充，用來寫 RESTful API 文件

工具

API Blueprint 官網有列出許多工具，推薦網站Apiary。免費註冊後就能在線上編輯文件，左右對照 Markdown 和預覽結果，對於屬性有完整支援。

Aglio 則用來把 Markdown 轉成 HTML，安裝與使用方法如下：

# 在 Debian 11 上安裝

# 先安裝 Node.js
sudo apt install curl build-essential
curl -sL https://deb.nodesource.com/setup_16.x | sudo bash -
sudo apt install nodejs

node -v
npm -v

# 使用 npm 全域安裝
sudo npm install -g aglio

# 也可以用 yarn 安裝
# 安裝 yarn
sudo apt install curl gnupg
curl -sS https://dl.yarnpkg.com/debian/pubkey.gpg | sudo apt-key add -
echo "deb https://dl.yarnpkg.com/debian/ stable main" | sudo tee /etc/apt/sources.list.d/yarn.list
sudo apt-get update
sudo apt-get install yarn
yarn --version

# 使用 yarn 全域安裝
sudo yarn global add aglio

接著編輯好 markdown 檔案，例如 example.md，然後執行 aglio -i example.md -o example.html ，轉換成 example.html。可以執行 aglio 指令看看參數有哪些。可以使用 aglio -i example.md -s -h 0.0.0.0 -p 8000 產生即時預覽。

API Blueprint on Tom 除錯中

使用 API Blueprint 寫文件

工具