使用 Swagger
協助你打造出更好的 API
by 劉艾霖
About Me
@alincode
- JAVA DEV for 5 years
- SDET for 8 months
- PM for 6 months
- JS DEV for 2 years
- 培訓師 for 2 years
- Work Remotely for 3 years
- 創立「遠距工作者在台灣」
-
會員人數：七百多
-
宗旨：遠距工作經驗交流 & 職缺分享
-
主辦 / 協辦活動
Outline
-
Old Way
-
什麼是 Swagger
-
從零開始
-
舊專案
-
Demo
Old Way
what's the problem?
OK...
什麼是 API
那什麼是好的 API
好的 API 應該具備
-
詳細的文件，文件與程式碼規格一致
-
API具有可預測性，命名一致性與對稱性
-
容易於閱讀和容易於學習
-
不要模擬兩可，不容易誤用(防呆)
-
結果正確、安全性考量、效能考量
-
良好的封裝，介面跟實作不會互相影響
你有沒有發現什麼？
什麼是 Swagger
Swagger is a set of open-source tools built around the OpenAPI Specification that can help you design, build, document and consume REST APIs.
The major open source tools
-
Swagger Editor -
Swagger UI -
Swagger Codegen
網頁版的 OpenAPI specs 編輯器
- 快速建構 UI
- 以互動式 Web UI 呈現
- 簡易測試
-
介面
- 顏色
- Tag
- 防呆
- Common Mark
- 範例
-
根據 OpenAPI spec 產生
-
server stubs (for mock server) -
API client
-
-
支援各種程式語言
-
NodeJS
-
JAVA
-
C#
-
Ruby
-
Go
-
...more
-
圖片來源：SmartBear
-
SwaggerHub
-
Swagger Inspector
Platform
SwaggerHub
-
Editor + UI + Codegen
-
權限管理 + 協作 + 分享
Swagger Inspector
- 很像 Postman
-
提供簡單的 API 測試
- 生成文檔
誰有用它？
全世界都在用 Swagger
-
IBM
-
Microsoft
-
NETFLIX
-
Expedia
-
...
從零開始
要怎麼做
1. 從上到下
2. 從下到上
從上到下 ---> 適合新專案
從下到上 ---> 適合舊專案
情境：新專案
人物介紹
IOS 工程師 x 2
Android 工程師 x 2
SA & SD & 後端工程師 & 窗口
全端工程師 x 2
窗口 & PM
8 個人同時 Cowork
T 公司
B 公司
遇到的挑戰
多人並行
多種環境
資訊落差
在這個專案，我們採用
Schema-First API Design
The schema-first API design approach advocates for writing your API definition first in one of many API specification languages before writing any code.
需求
分析
設計
實作
部署
維護
生命週期
需求分析階段
需求階段
-
進行需求討論時，一切以 API 文件為中心 - 定義 Model 跟 API 的基礎
-
將討論結果，產出第一版的 API 文件
-
最後要將文件做版本控管
get /api/todos:
post /api/todos:
patch /api/todos/{todoId}:
delete /api/todos/{todoId}:openapi: 3.0.0
info:
title: TODO API
description: The TODO API
version: '0.1'
servers:
- url: 'https://localhost'
paths:
...paths:
/api/todos:
get:
description: "取得所有 TODO"
responses:
'200':
description: ""
post:
description: "新增 TODO"
responses:
'200':
description: "" /api/todos/{todoId}:
patch:
description: "更新 TODO"
parameters:
- in: path
name: todoId
schema:
type: integer
required: true
description: TODO ID
responses:
'200':
description: ""
delete:
description: "刪除 TODO"
parameters:
- in: path
name: todoId
schema:
type: integer
required: true
description: TODO ID
responses:
'204':
description: ""components:
schemas:
TODO:
type: object
properties:
id:
type: integer
text:
type: string
checked:
type: boolean定義 Model
設計階段
-
取得 feedback，補齊 API 文件細節
-
舉行第二次 API Review 會議
實作階段
-
自動 - 透過 codegen 產生基礎程式碼基礎架構-
Server Side code (for mock server)
-
Client Side code
-
測試程式碼
-
-
手動
-
看著文件，照著文件內容實作
-
實作階段
-
補足遺漏
-
切記先寫 API 文件，才寫 Code。
-
嚴格要求照圖施工
-
以 API 文件內容為準，做驗收
Co-work 的期間
我相信你一定曾遇這樣的情境
你的 API 有問題歐，我抓不到資料
是嗎？我每隻 API 都有寫單元測試
我剛剛用 Postman 測，也是正常
我剛剛也是用 Postman 阿，不然你截圖給我看看。
工程師就暴走了
所以問題發生在哪？
讓其他人分擔
撰寫 API 文件的工作
教育訓練
-
示範怎麼正確的使用 Swagger UI -
傳授 Restful 設計風格
- 怎麼切 Component
-
說明已經自行定義好的慣例
- 做過的適度的教育訓練，之後就可以開始進行分工。
部署
- 結合版本控管系統自動更新文件
- 提醒：分別設定 Dev 和 Production 存取文件的權限
維護 & 驗收
- 當異常出現時， 透過文件UI 檢驗 Response 結果
- 改版時，可透過 版控系統，管理跟查看更變
- 也可方便 測試人員瞭解 API
- 作為開放平台開發者的手冊
- convert swagger to PDF
簡易查詢後台
- 測試寄信功能
- 重寄報表
- 查看狀態
實施重點
-
一切以 API 文件為中心
-
使用統一的平台
-
使用版控系統
-
嚴格要求，照圖施工
-
教育訓練
-
權力下放
舊專案
-
swagger decorator 自動轉出文件
-
透過 Swagger Inspector 匯出基礎版本的文件
export default class UserController {
@apiRequestMapping("get", "/user/:id")
@apiDescription("get user object by id, only access self or friends")
@pathParameter({
name: "id",
description: "user id",
type: "integer"
})
@queryParameter({
name: "tags",
description: "user tags, for filtering users",
required: false,
type: "array",
items: ["string"]
})
@apiResponse(200, "get user successfully", User)
static async getUserByID(ctx, next): User {
...
}
}Demo
先編寫 API definition 好處
改善 API 設計
-
透過工具可以儘早學習，並提供回饋。
-
提前測第三方 API without coding
-
前端團隊可以立即開始動工，不用等後端全部實作完。
-
可以比傳統方法更快地進行
讓跨團隊更快的進行
-
透過 codegen
-
透過 swagger UI
快速建立 API 建立測試
快速產生原始碼和文件
-
透過 codegen 產生
-
server side 跟 client side 的 code
-
-
透過 OAS
-
產 Swagger UI
-
產 PDF 文件
-
Demo
https://github.com
/alincode/modern-web-2018-swagger
https://editor.swagger.io/
總結
-
Swagger 讓寫文件不在是浪費時間的事，而是緊密地與開發流程結合，達到加速團隊開發效度
-
Swagger 漸漸取得獨大的地位
-
標準化之後的後續效應，是可以期待的。
-
2.0 -> 3.0 還在轉換期
-
若是不公開的 API 文件，上線時記得 lock 權限。
小提醒
-
Swagger Editor 有時候不太穩
-
錯誤提示有點太簡略
缺點
更多資源
OAS 在 API 設計階段的幫助
-
它可以讓你先專注在定義 interface-
輸入
-
輸出
-
schema 定義
-
Authentication
-
-
標準化 OAS 3.0-
REST-ful
-
Component
-
Reusable
-
info:
title: defaultTitle
description: defaultDescription
version: '0.1'什麼是 OpenAPI Specification
OpenAPI 3.0
-
由 SmartBear 捐給 Linux 基金會的 OpenAPI initiative 組織 -
基於 Swagger 2.0 規格基礎做改良 -
OAS 3.0（OpenAPI Specification)
openapi: 3.0.2
info:
title: Star War API
description: The Star War API
version: '0.1'
servers:
- url: 'https://swapi.co'
paths:
/api/people:
get:
description: Auto generated...
responses:
'200':
description: Auto generated...-
不依賴語言跟框架 (codegen)
-
可以驗證，可以測試 (editor)
-
可視化快速回饋介面 (editor)
-
它很簡單、容易懂 (OAS)
-
易於維護 (OAS)
-
豐富的生態系，支援完整的 API Lifecycle
優點
responses:
'200':
description: ""
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/TODO'替 Response 新增 Content
responses:
'200':
description: ""
content:
application/json:
schema:
$ref: '#/components/schemas/TODO'