Parameters - 用來定義URI Template的部分

回到之前的TODO 功能API的範例。

假設，今天取得所有的ToDo的這一支API想要加上一次出現幾筆資料，那麽一般來説這個設定會屬於網址的一部分，可能是用query string呈現或者route的一部分。

這個時候就是要用URI Template來定義。

大概操作會是：

1. 調整路由，包含幾筆資料這個參數
2. 增加Parameters，定義參數含義

調整路由，包含幾筆資料這個參數

以這邊的例子將會用PageSize作爲一次幾筆的參數，以及currentPage代表目前是在第幾頁，那麽：

### 取得所有的ToDo [GET /api/todo{?pageSize,currentPage}]

這邊用一個中括弧({})把所有的參數包起來，以問號(?)作爲開始表示屬於Query String，如果沒有問號則表示是URI的一部分。

增加 Parameters，定義參數含義

有了參數名稱之後，接下來就是要定義這些參數代表什麽意思。

首先會先增加一個 Parameters的區塊，然後裡面列出每一個URI Template定義的參數説明。

例如：

### 取得所有的ToDo [GET /api/todo{?pageSize,currentPage}]

+ Parameters
    + pageSize: 10 (number, optional) - 幾筆資料
    + currentPage: 1 (number, optional) - 第幾頁

這邊要注意幾個地方

• 每一個開始都是用+做開頭 - 這個用來區分告知是某個區塊或者某一組
• 每一個大項目會投過空一行來作爲區隔
• 如果是在一起，但是是清單，那麽會寫在下一行，但是用tab或者4個空白表示下一層内容 - 例如 pageSize 就屬於Parameters的一部分所以是用空一行然後tab

這邊定義欄位的格式是用一種叫做MSON的格式定義，詳細下一篇會介紹，但是基本格式為：

<parameter 名稱>: `<範例值>` (<型別>, required | optional) - <描述>

定義好了之後，看文件的時候這兩個參數就會出現了：

Request 定義傳入的内容

一個TODO的APP如果不能夠新增的話，那麽就沒什麽用，所以要建立一個用來新增資料的API。

一般新增會挑選使用POST這個http verb，因此如果今天要定義一個接受JSON，裡面有個欄位是title，代表要建立的内容，那麽撰寫起來會是：

### 新增一筆TODO [POST]

用來新增一筆TODO

+ Request (application/json)

        {
            "title": "記得要買牛奶"
        }

其實還滿直覺，使用 Request區塊定義允許接受傳進來的内容，然後定義一個返利格式出來。

單純回傳body内容

首先以取得所有的ToDo為例子，回傳的内容是一個array，裡面的物件就兩個欄位：id以及title：

### 取得所有的ToDo [GET /api/todo{?pageSize,currentPage}]

+ Parameters
    + pageSize: 10 (number, optional) - 幾筆資料
    + currentPage: 1 (number, optional) - 第幾頁

+ Response 200 (application/json)

        [
            {
                "id": 1,
                "title": "要買牛奶"
            },
            {
                "id": 2,
                "title": "要修好bug 123"
            }
        ]

回傳包含header内容

如果説今天是呼叫了POST去建立一筆資料，如果今天走的是RESTFul的風格，那麽理論上header應該要回傳建立出來的資源的URI是什麽。

這個時候就可以用Headers這個區塊，不過因爲有了Headers，那麽就需要明確定義那邊是Body：

### 新增一筆TODO [POST]

用來新增一筆TODO

+ Request (application/json)

        {
            "title": "記得要買牛奶"
        }

+ Response 201 (application/json)

    + Headers

            Location: /api/todo/4

    + Body

            {
                "id": 4,
                "title": "記得要買牛奶"
            }

定義多個不同的response

有時候因爲傳入内容不同，response也會有所不同。

舉例來説，當呼叫POST的時候，但是title是空的，那麽應該會回傳一個400帶訊息告訴說，title是必填欄位

這個時候就可以在加入一組Response代表這個情況：

### 新增一筆TODO [POST]

用來新增一筆TODO

+ Request (application/json)

        {
            "title": "記得要買牛奶"
        }

+ Response 201 (application/json)

    + Headers

            Location: /api/todo/4

    + Body

            {
                "id": 4,
                "title": "記得要買牛奶"
            }
            
+ Response 400 (application/json)

    驗證失敗

    + Body
    
            {
                "erroMessage": "title是必填欄位"
            }