Day19 撰寫api文件

上一篇文中，我們講了如何設計api。api是開出來了，可是這之api只有你會用啊，我要怎麼讓前端知道怎麼串接我的api？靠的就是api文件。api文件就像是專案的說明書，沒有說明書，使用者就不知道怎麼用。
今天我們就用上一篇的例子，寫出api文件吧。

api元素

api文件個人寫法都會有些不同，就像寫文章一樣，有些人可以把文章寫的很好，讓人一看就懂，而小弟我並不是個很會表達的人，我說的廢話不多，比較言簡意賅，所以今天就講講我的api文件中不可或缺的元素有哪些吧。

• title 說明
• URI
• method
• request
  • header
  • body
• response
  • status code
  • header
  • body

一個api該有什麼，簡單講就是，你要清楚明瞭的表示前端要輸入什麼、後端就會給什麼。

上面最基本的元素有了之後，基本上前端就能進行串接啦，但是我會希望api文件更加完善些，省去我向前端解釋的功夫。我會儘量標註說明，簡單的說明這支api是什麼功能，而我只允許輸入什麼type的資料等等。

1. 註解
2. 輸入資料的type，長度
3. 錯誤情況

api範例

假設我api是這樣寫的

route:

Route::get('task/{id}','api\TaskController@show');

controller:

    public function show($id)
    {
        $task = Task::find($id);
        if (!$task) {
            return response()->json(['status' => false, 'error' => 'task search not found'], 400);
        }
        return response()->json(['status' => true, 'task_data' => $task], 200);
    }

而我的api文件內會這樣打：

• show task(使用task id 搜尋task)
• URI:127.0.0.1:8000/api/task/{id}
• method:GET
• request
  • header

    {
    "Content-Type" : "application/json",
    "userToken" : "userToken"
    }
    

    userToken取得：
    127.0.0.1:8000/api/userToken
  • body
    N/A
• response
  • status code 200

    {
    "status": true,
    "task_data": [
        {
        "id": 2,
        "titel": "task1",
        "status": false,
        "create_user": "admin",
        "update_user": "admin",
        "description": null,
        "tag": null,
        "image": null,
        "card_id": 10,
        "created_at": "2020-09-07T05:31:09.000000Z",
        "updated_at": "2020-09-07T05:31:09.000000Z"
        }
        ]
    }
    

  • status code 400 (task id 輸入錯誤)

    {
        "status": false,
        "error": "task search not found"
    }
    

上面的api文件都是找過前端討論出來的，像是response的格式，哪邊是字串，哪邊是數字等等，都必需經過討論。格式的部份，我之前就有遇過一個問題，前端是ios 是用Swift語言，而我是PHP，一個是強型別一個是弱型別，對我來說布林值true,false 跟1,0 是互通的，但swift不通。像這類的問題就需要講好輸入輸出得格式才好串接。

其實api文件也有些工具可以使用，這部份我目前還沒研究，目前都是手動寫，之後有工具覺得好用的話，再分享我的心得吧。
以上我分享的純屬個人作法，每個人寫api文件方法都不一樣，若有不妥之處，歡迎高手留言指教，今天就介紹到這邊，Bye!