Skip to main content

[note] 使用 Apiary 與 API blueprint 撰寫 API 文件

常見功能#

分組:Resource Group#

# 後面加上 Group 關鍵字可以將 API 文件分組,例如:

# Group 空間(Space)
以下為功能與「空間(Space)」相關的服務

否則預設都會在同一個 Resource Group 內

資源:Resource#

Resouce 指的是 API 的 endpoint,一般就是能夠操作某個「資源」的網址。舉例來說,想要對空間(Space)進行 CRUD 時,Resource 可能會長這樣:/spaces

接著再針對這個 Resouce 進行不同的動作(Verb),例如 GET, POST, DELETE, PATCH, PUT 等等。

要建立 Resource 的話使用 ## 後面加上說明文字,最後用 [] 把 resource 的 enpoint 放進去:

## 空間(Space) [/api/v1/spaces]

動作:Action#

如果執行的 HTTP Verb 和 Resouce 定義時的 endpoint 一樣的話,可以直接在 [] 中加上 HTTP 動詞,例如:

### List All Spaces [GET]

但如果 endpoint 有變動的話,可以在 [] 內加上變更後的 endpoint,例如在取得某一筆 Space 資料時:

### Get Space [GET /api/v1/spaces/{spaceId}]

常用 Template#

Metadata, API Name & Description#

FORMAT: 1A
HOST: http://localhost:5000
# jubo-space
Jubo Space API 可以用來對空間(space)、裝置(device)與偵測(detection)進行 CRUD。

List API#

### List All Spaces [GET /api/spaces/{?name,branch,room,bed}]
在路由的地方使用 `{}` 把參數包起來,如果最前面有加上 `?`,表示它是 qeury string,否則會屬於 URL 中的 params。
使用 `+ Parameters` 可以定義每個 query string 的意義。撰寫時遵行的是 `MSON` 的格式,長像這樣
`` <parameter 名稱>: `<範例值>` (<型別>, required | optional) - <描述> ​``
- Parameters
- name: "台大醫院" (string, optional) - 空間名稱
- branch: "2" (string, optional) - 幾筆資料
- room: "103" (string, optional) - 房號
- bed: "A" (string, optional) - 床號
- Response 200 (application/json)
[
{
"id": "cbe05355-da81-41d3-8d2e-156120549c15",
"name": "仁康醫院",
"branch": "2",
"room": "101",
"bed": "B"
},
{
"id": "10557827-e7c7-4f25-a079-1f54369583e2",
"name": "仁康醫院",
"branch": "2",
"room": "105",
"bed": "C"
}
]

Get API#

### Get Space [GET /api/spaces/{spaceId}]
- Response 200 (application/json)
- Body
{
"id": "cbe05355-da81-41d3-8d2e-156120549c15",
"name": "仁康醫院",
"branch": "2",
"room": "101",
"bed": "B",
"devices": [
{
"id": 1,
"boxDeviceId": "jubo00001",
"name": "MWG Bed Mattress",
"type": "mattress",
"description": "美維智慧床墊",
"state": "NORMAL",
"message": "",
"configuration": null,
"detections": [],
"spaceId": "cbe05355-da81-41d3-8d2e-156120549c15"
}
]
}
- Response 404 (application/json)
找不到該 Space
- Body
{
"error": "record not found"
}

Create API#

### Create a Space [POST /api/spaces]
建立新的 Space
- Request (application/json)
{
"name": "仁康醫院",
"branch": "1",
"room": "101",
"bed": "B"
}
- Response 201 (application/json)
- Body
{
"id": "f1b92899-3ea3-450f-97ea-838a4beb80f5",
"name": "仁康醫院",
"branch": "1",
"room": "101",
"bed": "B",
"devices": []
}

參考資料#

Last updated on