by 劉艾霖
會員人數:七百多
宗旨:遠距工作經驗交流 & 職缺分享
主辦 / 協辦活動
詳細的文件,文件與程式碼規格一致
API具有可預測性,命名一致性與對稱性
容易於閱讀和容易於學習
不要模擬兩可,不容易誤用(防呆)
結果正確、安全性考量、效能考量
良好的封裝,介面跟實作不會互相影響
Swagger is a set of open-source tools built around the OpenAPI Specification that can help you design, build, document and consume REST APIs.
Swagger Editor
Swagger UI
Swagger Codegen
根據 OpenAPI spec 產生
server stubs (for mock server)
API client
支援各種程式語言
NodeJS
JAVA
C#
Ruby
Go
...more
圖片來源:SmartBear
Editor + UI + Codegen
權限管理 + 協作 + 分享
提供簡單的 API 測試
IBM
Microsoft
NETFLIX
Expedia
...
要怎麼做
IOS 工程師 x 2
Android 工程師 x 2
SA & SD & 後端工程師 & 窗口
全端工程師 x 2
窗口 & PM
T 公司
B 公司
多人並行
多種環境
資訊落差
進行需求討論時,一切以 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
取得 feedback,補齊 API 文件細節
舉行第二次 API Review 會議
自動 - 透過 codegen 產生基礎程式碼基礎架構
Server Side code (for mock server)
Client Side code
測試程式碼
手動
看著文件,照著文件內容實作
補足遺漏
切記先寫 API 文件,才寫 Code。
嚴格要求照圖施工
以 API 文件內容為準,做驗收
你的 API 有問題歐,我抓不到資料
是嗎?我每隻 API 都有寫單元測試
我剛剛用 Postman 測,也是正常
我剛剛也是用 Postman 阿,不然你截圖給我看看。
示範怎麼正確的使用 Swagger UI
傳授 Restful 設計風格
說明已經自行定義好的慣例
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 {
...
}
}
它可以讓你先專注在定義 interface
輸入
輸出
schema 定義
Authentication
標準化 OAS 3.0
REST-ful
Component
Reusable
info:
title: defaultTitle
description: defaultDescription
version: '0.1'
由 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...
responses:
'200':
description: ""
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/TODO'
responses:
'200':
description: ""
content:
application/json:
schema:
$ref: '#/components/schemas/TODO'