亂中有序，才怪…

本文大綱

目錄

前言

近期，自己在研究 Api 文件化，剛好公司這方面還沒有人導入，
成了我第一次自動請纓去研究一套工具的契機，如果研究後，發現看 Api document 可以順利導入，成就感應該爆棚XD 那麼 Api docs 到底有什麼好處？
好端端的，為什麼需要導入一個陌生的工具去建立文件？
在公司 project codebase 中你是否看過在 function 上面有這些註解？

TodoController.php
  • php
1
2
3
4
5
6
7
8
9
10
 
    /**
     * Display the specified resource.
     *
     * @param  int  $id
     * @return \Illuminate\Http\Response
     */
    public function show($id)
    {
        ...business logic
    }
上面程式碼，都是下一個工程師(你或我)在下一次看到這段程式碼時，看到這些註解，可以幫我們快速了解，這段 code 的商業邏輯，以及它要處理什麼事情。
那 PM 怎麼知道這個 Api 在做什麼呢？
或是對外的工程師怎麼知道呢？
他們沒有權限看到上面這段程式碼， 他們怎麼知道這個 api route 連到哪個 controller？ 需要代哪些參數？
滿滿的問號，需要滿滿的大平台去回答以上這些問題，總歸一句， 我到底要怎麼快速且無痛的使用這個 Api 完成我想做的事情，
我沒有某某專案權限，我想要串這個 Api，我問問某某工程師，說不定他知道這個 Api 在幹嘛 XD
所以說，這個「某某工程師」必定要很多美國時間，要很懂這個 project，且要在很快的時間內回答我的問題。
上面說的「某某工程師」就是開發這個 Api 的工程師，他們會寫 word/notion 等等文件管理工具，用文件向 PM、其他工程師，Api 怎麼使用。
  • text
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
 
1. read: Get api/todo/{id}
    params: none
    response:
        a.
        {
            "code": 200,
            "message": "",
            "data": [
                "id": 1,
                ...data
            ]
        }
        b. 
        {
            "code": 204,
            "message": "",
            "data": []
        }
        c. 
        {
            "code": 404,
            "message: "not found",
            "data": []
        }
        d.
        {
            "code": 401,
            "message": "Unauthorized",
            "data": []
        }
    * 備註： cache 一小時
上面大致上就是給 PM 以及外包團隊的文件。
每個工程師都有自己偏好的寫文件的方法，當沒有一個統一工具去規範，加上文件又散落到各地，一下子 word，一下子內部文件、一下子 markdown 工具，就真的是一份文件，各自表述了！ 話說回來，哪一款文件管理工具團隊用起來比較容易上手、功能比較多，這不是一個選青菜還是蘿蔔的問題，這是一個需要團隊討論工具優缺點，決議討論好下手，就導入文件管理工具，一種規範，工程師每完成一個需求，就必須把文件補上，避免文件與程式不同步的狀況發生。 有了明確的動機後，我挑了兩個 Api document tool，Swagger & ApiDocs，讓我們一起來看它們的優缺點吧！

Swagger

先講結論，不賣關子，我們團隊後來選擇 Swagger 導入。
先看個畫面吧！給個感覺，才不會沒有憑空想像。 以下為 Swagger 提供的 Live demo

swagger
swagger 精美畫面 圖片來源 petstore swagger UI

優點：

  1. 介面好看
  2. 文件不會產生靜態檔
  3. 互動性操作高(有類似 Postman 功能)
  4. 網路資源多(可以快速找到寫法)，超級重要，不會的時候可以上社群問
  5. 其他產品部門有使用過(有人問總比沒人問好)
  6. 相較於 ApiDocs，較多團隊使用 Swagger 作為 Open Api

缺點：

  1. 寫法較難上手
  2. 寫法在頁面上看起來很冗長

這邊補充一下 Open Api 是什麼？ Open Api Specification 又是什麼？ 這裡有一個 Open Api 網站畫面，讓讀者更容易想像。

Open Api 是對大眾公開的 Api 介面，可以給每個開發者使用與操作，因此可以藉由這些 Open Api 取得資料。
每個工程師都有自己寫文件的方法，因此 Open Api Specification 就是 Open Api 的規範，又可簡稱為 OAS，有一個明確且公認的規範去撰寫這些文件。
舉例來說：想要串 Twitch 直播的 Api，你可以先看 Twitch 提供的 Open Api。

ApiDocs

swagger
apidocs 精美畫面 圖片來源 Learning Laravel

優點：

  1. 寫法簡單上手快
  2. 寫法精簡，跟註解 PHP Docblocker 寫法很像，不會太難懂

缺點：

  1. 產生靜態檔 markdown 與一些 css
  2. 研究後發現，每次有修改都要執行一次，重新產生靜態檔
  3. 網路資源少
  4. 功能沒有互動性
  5. 研究後還找不到 snippets

學習重點

這是我目前擔任工程師後，第一次試著向團隊說明，說服團隊讓我嘗試導入一個新的工具在專案中，我也分析了不同 Api docs 的優缺點，讓團隊有共識，並進行良好的溝通與討論！ 最後選擇 L5-Swagger 進行導入原因歸納有以下三點：

  1. 使用者畫面好看
  2. 其他開發團隊導入過，如果不清楚有人可以詢問
  3. 不用產生靜態檔，可以自己重新 re-render，不用一直重複下指令
    由此可見，工具方便性、使用者畫面、有前人可以問是多麽重要的事情XDD
    這次研究 Api docs 工具中，也認識了新的名詞 Open Api，經過研究後，筆者認為立意是良好的，且有其必要性。

在團隊內，可以作為 PM 或是其他非此專案開發者，快速理解與操作 Api 的文件，對外合作廠商或外包團隊，可以使用 Open Api 標準格式，讓他們在測試環境中，能更快速了解如何串接與使用它， 不管選擇哪一個 Api docs 工具，主要的目的都在於，可以讓團隊更有效降低溝通成本，提升開發效率！

很開心這次導入成功，增加了溝通與導入工具上的經驗，真是可喜可賀！ 下一篇來說明 swagger 在 laravel 的寫法。

參考連結