跳至主要内容

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

參考資料​