# 使用 Swagger 協助你設計出更好的 API - 劉艾霖 (Alin)

{%hackmd j86FNbMoRoeN4Xn0pg5ofw %}

> 請從這裡開始

* [Live 投影片](https://slides.com/alincode/modern-web-2018-swagger/live#/)
* [完整投影片](https://slides.com/alincode/modern-web-2018-swagger/fullscreen)

## Outline
* old way
* 什麼是 swagger
* 從零開始
* 舊專案
* demo

## Old Way
* 使用 word 檔等，手動描述、版本…
### 問題在哪？
* 第一支文件非常詳細，第二支 api開始文件變少，然後就不更新了。
* 每個格式都是從第一個 template copy 過來的

> 然後就不寫文件了。
>

### 什麼是 api？
重點是 interface
別人跟你溝通的管道
>不是自己爽就好！ 要別人易用
>
#### 好的 api 應具備
* 詳細的文件、文件與code一致
* 可預測性，namespace 一致
* readable、容易學習
* 不要模擬兩可，不易誤用
* 正確、安全性
* 良好的封裝實作

### swagger　
是一個圍繞在 open source　工具的集合，可以協助在 api設計與建構與文件的階段提供幫助。
* swagger editor
編輯，文件中直接反應
* swagger UI
可點擊、可測試、可填寫參數、防呆
* swagger codegen
根據 openapi spec 產生
支援各種語言

### swagger hub
* 把上面三個東西集合起來變成一個平台

### swagger inspector
* 類似 postman
* 提供測試，請求歷史記錄
* 可測試完後，匯出想要的格式

## 從零開始 要怎麼做？
1. 從上到下
* 現在沒 code，從文件 design 開始才 implement
* 適合新專案
3. 從下到上
* 已有 code，補 doc
* 適合舊專案

> 並沒有哪一種比較好，只是情境的差別！

### 遇到的挑戰
* 多人並行
* 多種環境
* 資訊落差

> 採用 schema-first api design
> -- 在寫 code 之前，先做 api define

#### 需求分析階段
* 進行討論時，一切以 api 為中心
* 定義 model schema 跟 api 基礎
* 將討論結果產出第一版 api 文件
* 上 git

##### open api
* path
* http verb
* request schema
* response schema

> 有文件後，即可使用 swagger 工具產生 UI ！

#### 設計階段
* 取得 feedback 補齊 api 文件細節
* 舉行第二次 api review
* 因為已經使用過，所以可以繼續改善

#### 實作階段
* 自動
* 透過 codegen 產生基礎程式碼
* server side code (for mock server)
* client side code
* 手動
* 看著文件，照文件內容實作
* 補足遺漏
* 切記先寫 api 文件，才寫 code
* 嚴格要求**照圖施工**
* 以 api 文件內容為準，做驗收

> 很少有人真的這樣做，大部分都是先實作才寫文件。

_額外的小意外_
> 對方：你的 api 有問題，抓不到資料
我：是嗎？ 我 api 都有 unit test，剛剛用 postman 都正常。
對方：我剛剛用 postman 啊，不然你截圖我看看。

第一次被問 :)
第二次 :|
第三次 :(
第四次 = =|||

##### 問題在哪？
* postman 的問題
* 參數太多，head、body 設錯，容易錯誤
* 應該要用一個統一的介面
* 使用 swagger ui (限制可變動的地方)
* 大家都用 swagger ui，就像是第三方公正平台

#### 教育訓練
> _要想辦法分擔其他人也可以分擔寫文件工作_
* 示範怎麼正確地使用 swagger ui
* 傳授 restful style
* 怎麼切 component
* 說明已經自行定義好慣例

就可以開始分工！

#### 部署
* 結合scm自動 update doc
* [提醒] 要分別設定dev 與 prod env

#### 維護 & 驗收
* 當異常時，可透過文件 ui 驗證response 結果
* 改版時，可透過版控系統，管理查看及變更
* 也可方便測試人員瞭解 api
* 作為開放平台 developer 的文件
* 轉換 swagger 變成 pdf 文件

> swagger 也可以做為簡易查詢後台
>

### 舊專案 (下到上)
* 使用 swagger decorator 自動轉出文件
* 透過 swagger inspector 匯出基礎版本的文件
* 插入中介層，parse request 找出 request form and response (這個好酷)

### [DEMO](https://github.com/alincode/modern-web-2018-swagger)
* [https://github.com/alincode/modern-web-2018-swagger](https://github.com/alincode/modern-web-2018-swagger)

## summary
* 以前覺得寫文件浪費時間
* 文件本來就是開發流程的一個環節之中，加速團隊的開發速度
* 目前已經是 swagger 一個獨大的地位
* 標準化之後的後續效應，是可期待的。

###### tags: `MW18`