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": []
}

參考資料