大概兩年前吧，我就有接觸到 open API 或類似 Swagger 的工具，但礙於工作環境，一直都無法將這些觀念實做到工作環境中，最近終於有個機會，可以讓我調整 API 文件的處理方式，想說也可以藉由這次的機會，也順帶跟大家分享一下 API first 的東西。
(API first 的內容大多取至 Andrew 在 2022 DevOps Day 分享的內容 ，我這邊主要擷取了一些我吸收的東西，並做了一些與個人經驗上的分享)
You will know…
- API first 是什麼? 從不同角色出發會有什麼不同的考量?
- Code First V.S API First – 流程比較
- 現狀分析 – 想像情境分析
- Swagger LAB 實做
- open API 3.0 yaml 說明
- 建立第一個 API doc
- mock API
- generate code by doc
- import to postman
API first 是什麼? 從不同角色出發會有什麼不同的考量?
API 設計的順位要擺在第一，之後才去思考 UI, DB, 系統架構等等
如上，在不同角色會需要思考:
- 產品經理: UI 優先還是 API 優先?
- 技術經理: 要先有會動的產品出來，在去重構 API 呢? 還是 API 規格先訂好，前後端在一起實做?
到這裡，我推薦大家可以停個 30 秒，在腦中情境模擬一下，不同的思考面向，所碰到的優缺點有什麼? 列出來後，再去思考你真正想要達地的目的或是解決的問題是什麼?
我這邊想像的情境如下:
有一個公司 A，跑敏捷開發，一周迭代一次
| 選擇 | 好處 | 隱憂 |
|---|---|---|
| UI 優先 | 能實體看到畫面所呈現的樣子 | 思考面向較為單一，回饋有限，容易被限制在 UI 框架中 |
| 會動的產品優先 | 能較早收集使用者真實回饋 | 開發體驗差，技術債隱憂 |
| API first | API 是前端, 後端, 各團隊相互的橋梁，提早有共識可降低後續溝通成本。 API 規格出來後，可以讓各團隊同時獨立作業，加上 mock API 的加持，QA 或架構師也可以在這個基礎上進行進一步的測試以及驗證。 | 對於 domain 知識不足的團隊，無法在第一時間開出較為嚴謹的規格，嚴重的話可能導致做白工的現象。 |
總結來說，可以用下面這張圖來跟大家說明:
API 成了各部門組織的共通語言，達成了共同的目標與共識，有了一樣的開發藍圖，再走向下一步，以減少後續的溝通成本。
Code First V.S API First – 流程比較
左邊的流程，相信大家都很熟悉，需求分析結束後，開發者開始從系統架構、資料庫…(外圍)，往需求、程式碼、API 接口(內圍)收斂，這樣的流程容易侷限了 API 的彈性，較難被模組化甚至是走向商業化的境界。
而右邊的流程，看似複雜了許多，但卻對於開發者體驗上有很大的提升，也一定程度的降低了團隊溝通的成本。各團隊在 API 規格與 mock API 完成後，就可以依據相同的藍圖，進行後續作業，提高共識，降低依賴。
現狀分析 – 想像情境分析
困難與個人解方:
- 我既不是產品經理也不是技術經理，要發起這樣的變革，距離是真的遙遠
- 就算不是採用 API first 的運作方式，也是可以在每一次完整的需求迭代後，進行整理與反省，也可以學到好與壞的 API 設計差異是什麼。
- 假設運氣真的很不好，每次遇到的主管都是較為保守、無法與時俱進的話，我覺得可以去嘗試思考看看: 如果自己要去擔任或是應甄這類型職位，你缺少什麼能力? 多面試幾間就會有答案了，累積到一定的能力之後，我相信你也累積到一定的視野，應該就知道該怎麼做了。
- 軟體工程師一定免除不了維護舊系統，以及在舊系統上修改或是增加功能的工作，那如果在一個舊系統上，採用 API first 的方式進行維護及開發會導致什麼呢?
- 我想有 8 成的機率會開出主管無法接受的工時，然後會有一堆看不見的坑在等著你踩 (取決於舊系統的技術債多少)。個人建議，如果要採用 API first，一定要先完整熟悉舊系統的架構與商業邏輯，然後在合理的成本下 ，進行 API first 的運作。(可以的話，要先把坑填滿，然後評估舊系統目前的商業價值是否符合成本)
- 害怕經驗不足，不敢嘗試這樣的改變
- 如果公司沒有辦法給你這樣的環境讓你嘗試，那就自己創造一個吧，side project 不就是這樣產生的嗎? 社會有社會的遊戲規則，沒有辦法在主線改變規則，那就為自己分叉一條吧，你可以獲得不當小螺絲所帶來的成就感與視野。
Swagger LAB 實做
swagger 是一個 API doc 的工具，可搭配 API first 使用
open API 3.0 yaml 說明
建議大家可以去參考 swagger 現成的 restful API 範例，寫得蠻詳細的，這邊我就偷懶一下，有時間再補詳細說明。
LAB 代補 …
The ReXTein 