撰寫API的利器-apidoc

身為前端工程師的我們，在寫專案的過程中你是否也有需要"通靈"的時候? 或許有或許沒有，當我一開始進到 Lion F2E時，前輩常講你來這邊學會的第一件事就是"通靈"XD

所以開發專案需要"通靈"到底是什麼意思?

一個專案開始進行時後端在api還沒完成的情況下，前端套資料時必須要猜測後端可能之後開出的資料格式的狀況。或許這種狀況比較容易發生在大公司，當前後端工作需求項目不同時，前端開發進度會比較快(像我們team就是這樣，後端都還沒開始開發api。前端已經切完版了，但第二階段串接api卻無法進行下去)

在需要"通靈"的狀況下，到底怎樣才能讓協同開發專案變得更有效率呢?

剛剛提到因為後端api還沒開始寫，因此我們只好自己先"通靈"寫api，雖然可能跟後端給的api會不太一樣，也可能非常不一樣，但我們至少可以用真正的api，並且讓畫面有資料。講到這邊，就要介紹撰寫api的好工具 — apidoc

Apidoc簡介與優點

• 透過源代碼中的注釋來生成API文檔
• 可以追溯不同版本寫的api並進行比對

先來看看apiDoc的語法與呈現

▲apiDoc原始代碼與網頁上的呈現狀況

apiDoc 使用流程

Step 1: 安裝 apidoc

npm install apidoc -g

Step 2: 在專案資料夾中新增apidoc.json的檔案

在newApi2中創建apidoc.json資料夾

apidoc.json
{
   "name": "測試的Api文件",
   "version": "0.1.0",
   "description": "API 文件",
   "title": "測試的Api文件",
   "url": "https://localhost:3000/api"
}

Step 3: 加入欲讀取的api文件

加入myApp並把api文件檔案放進來(cart.js)

cart.js長相

可以發現內容部分裡面都是用註解的方式

api {CRUD方法(post)} url後綴(/api/cart/add) 項目標題(新增至購物車)
apigroup 表示api大項目
apiParam 參數

Step 4: 下指令產出頁面

newApi2的目錄底下輸入以下指令產出整理過後的API畫面

$apidoc -i myapp/ -o apidoc/
$apidoc -i 輸入的api文件夾/ -o 輸出的資料夾名稱/
i: input
o: output
如果還有自訂的template可以使用多加入template的指令(-t)
$apidoc -i myapp/ -o apidoc/ -t mytemplate/

▲下完指令後產生的apidoc

Step 5: 點開index.html看畫面呈現

以上就是簡單的apiDoc介紹!!

template部分基本上不太會用到，內建apiDoc產出的頁面基本上不會太難看，再加上主要的價值還是api文件內容及參數的型別、格式定義。更進階的用法也可以參考官網文件喔!!

參考資料

ApiDoc官網: http://apidocjs.com/