用 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 文檔
image 4 用 Aglio 新手小白也能做出美觀的 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 文檔了,是不是很簡單?

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

Blueprint 語法介紹

Resource Groups

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

寫法如下:

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

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

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

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

Include

你可能會好奇,# Group 使用者權限 是分區,那這個 <!-- include (user.md) --> 是什麼呢?

這是可以把其他檔案的內容給加進 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

0 0 評分數
Article Rating
訂閱
通知
guest

0 Comments
在線反饋
查看所有評論