用 Aglio 新手小白也能做出美觀的 API 文檔

最後更新於 2022 年 4 月 24 日

Aglio 是一個 API blueprint 渲染器，你只需要撰寫 Blueprint 語法(其實就是 Markdown) Aglio 就能幫你渲染出一個非常美觀的 API 文檔。

Aglio API Docs 用 Aglio 新手小白也能做出美觀的 API 文檔

Github：https://github.com/danielgtaylor/aglio

如果不熟悉 blueprint 語法，可以參考 API Blueprint 官方文檔，很容易就能上手。

創建藍圖及運行 Aglio

STEP 1

首先需要新建一個 apib 檔，就先假設為 test.apib 好了，這個檔案就是整個 API 文檔的核心，我們會把所有文檔中的內容通過直接撰寫、include的方式來集中在裡面。

創建 blueprint 的第一步是指定 API 域名和 API blueprint 的版本(非必要)：

FORMAT: 1A => 指定 API blueprint 版本為 1A
HOST: http://localhost:3000 => 指定 API base url 為 http://localhost:3000

我們可以先嘗試在檔案中加上一個一級標題、二級標題和段落文字：

FORMAT: 1A
HOST: http://localhost:3000

# DEMO API Docs
## 測試文字
測試 API 文檔

STEP 2

然後輸入指令 aglio -i test.apib -o api.html 來熱加載伺服器，這裡面的 test 為 apib 檔案名稱。

E:\aglio>aglio -i test.apib -s
Server started on http://127.0.0.1:3000/
Rendering test.apib
Socket connected
Refresh web page in browser

看到如上的文字後就可以打開瀏覽器輸入 http://127.0.0.1:3000/ 來預覽 API 文檔了，是不是很簡單？

Blueprint 語法介紹

Resource Groups

首先要介紹的第一個 blueprint 語法為 Resource Groups： # Group <Group name>

寫法如下：

# Group 使用者權限
<!-- include(user.md) -->

# Group 報表相關
<!-- include(report.md) -->

效果就是會區分出單獨一個區塊，可以將相同類型的 API 全部寫在一起：

Include

你可能會好奇，# Group 使用者權限 是分區，那這個  是什麼呢？

這是可以把其他檔案的內容給加進 blueprint 中，接受的檔案格式有：API Blueprint、Markdown 或 HTML。

Resource

在每個 Resource Groups 之中又會有好幾個 Resource，Resource 裡面還有 Action。每個 Resource 就像是群組中的子標題，而 Action 就是子標題中的子項。

用白話文來形容他們之間的關係的話大概是：

使用者權限 => Resource Groups

使用者資料 => Resource
查詢 => Action
新增
修改
刪除

登入與登出
登入
登出

用 blueprint 來寫的話可以寫成：

# 使用者權限
## 使用者資料 [/user/info/{id}]
### 查詢 [GET]
### 新增 [POST]
### 修改 [PATCH]
### 刪除 [DELETE]

## 登入與登出 [/user]
### 登入 [POST /user/login]
### 登出 [POST /user/logout]

開始編寫 API 文檔

接著上面的例子：

使用者資料旁邊的 [/user/info/{id}] 代表這個 resource 底下的 API 共通的 API 路徑為 /user/info/{id}。這個 id 需要在 Parameters 聲明。
參數聲明的範例：id: 1 (Integer, Required) - 使用者編號。
Request、Response 如其名，就是請求和回響，可以在回響旁邊加上狀態碼，來撰寫不同回響狀態碼的響應內容。
在 request 和 response 的右側加上 (application/json) 可以指定 Content-Type。

簡單寫一個 GET 的 action：

## 使用者資料 [/user/info/{id}]
### 查詢使用者資料 [GET]

可通過使用者 id 獲取使用者資料。

- Response 200 (application/json)
  ```json
  {
    "username": "admin",
    "roleName": "工程師",
    "role": 1
  }
  ```
- Response 403(application/json)
  ```json
  {
    "success": true,
    "message": "無權執行此操作"
  }
  ```
- Parameters
  - id: `1` (Integer, Required) - 使用者編號

其他新增、修改、刪除就是依樣畫葫蘆了：

## 使用者資料 [/user/info/{id}]

### 查詢使用者資料 [GET]

可通過使用者 id 獲取使用者資料。

- Response 200 (application/json)
  ```json
  {
    "username": "admin",
    "roleName": "工程師",
    "role": 1
  }
  ```
- Response 403(application/json)
  ```json
  {
    "success": true,
    "message": "無權執行此操作"
  }
  ```
- Parameters
  - id: `1` (Integer, Required) - 使用者編號

### 新增使用者資料 [POST]

以 form-data 新增使用者資料。
::: note

- 圖片上傳 `<input type="file" name="img">`
  :::

- Request (multipart/form-data)
  ```
  account=admin&username=admin&password=admin&role=2
  ```
- Response 200 (application/json)
  ```json
  {
    "success": true,
    "message": "新增使用者資料成功"
  }
  ```
- Response 403(application/json)
  ```json
  {
    "success": false,
    "message": "無權執行此操作"
  }
  ```
- Response 409(application/json)
  ```json
  {
    "success": false,
    "message": "帳號已存在"
  }
  ```

### 修改使用者資料 [PATCH]

可通過使用者 id 修改使用者資料。

- Request (application/json)
  ```json
  {
    "username": "admin",
    "role": 2
  }
  ```
- Response 200 (application/json)
  ```json
  {
    "success": true,
    "message": "修改使用者資料成功!"
  }
  ```
- Response 403(application/json)
  ```json
  {
    "success": false,
    "message": "無權執行此操作"
  }
  ```
- Parameters
  - id: `1` (Integer, Required) - 使用者編號

### 刪除使用者資料 [DELETE]

可通過使用者 id 刪除使用者資料。

- Response 200 (application/json)
  ```json
  {
    "success": true,
    "message": "刪除使用者成功"
  }
  ```
- Response 403(application/json)
  ```json
  {
    "success": true,
    "message": "無權執行此操作"
  }
  ```
- Parameters
  - id: `1` (Integer, Required) - 使用者編號

我們可以將以上與使用者權限相關的內容都丟到 users.md 裡面，然後在 apib 檔裡用 include 的方式引入：

mv0FORMAT: 1A
HOST: http://localhost:3000

# DEMO API Docs

# Group 使用者權限
<!-- include(users.md) -->

渲染成 html

輸入指令即可渲染成 html：aglio -i test.apib -o index.html，test 請改為你的 apib 檔名，index 為 html 檔名。

後記

範例檔案已放在我的 github 倉庫，有需要的可以參考：Aglio-demo

(如果是直接點開 md 檔瀏覽，記得點「display the source blob」才能看到完整的 markdown 程式碼)

更多的寫法、玩法可以參考：
1. Aglio github：https://github.com/danielgtaylor/aglio
2. API Blueprint Tutorial：https://apiblueprint.org/documentation/tutorial.html

閱讀量: 124