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
創立「遠距工作者在台灣」

會員人數：七百多
宗旨：遠距工作經驗交流 & 職缺分享
主辦 / 協辦活動

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
```

Swagger Editor

網頁版的 OpenAPI specs 編輯器

Swagger UI

快速建構 UI
以互動式 Web UI 呈現
簡易測試
介面
- 顏色
- Tag
- 防呆
- Common Mark
- 範例

Swagger Codegen

根據 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

資料來源：2017-03-22-共通性應用程式介面開放規範研議

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.

參考來源：dzone - Schema-First API Design

需求

分析

設計

實作

部署

維護

生命週期

需求分析階段

需求階段

進行需求討論時，一切以 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'

使用 Swagger

協助你打造出更好的 API

About Me

@alincode

Outline

Old Way

​什麼是 Swagger

從零開始

舊專案

Demo

Old Way

what's the problem?

OK...

什麼是 API

那什麼是好的 API

好的 API 應該具備

你有沒有發現什麼？

什麼是 Swagger

The major open source tools

Swagger Editor

網頁版的 OpenAPI specs 編輯器

Swagger UI

Swagger Codegen

SwaggerHub

Swagger Inspector

Platform

SwaggerHub

Swagger Inspector

誰有用它？

全世界都在用 Swagger

從零開始

1. 從上到下

2. 從下到上

從上到下 ---> 適合新專案

從下到上 ---> 適合舊專案

情境：新專案

人物介紹

8 個人同時 Cowork

遇到的挑戰

在這個專案，我們採用

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.

需求

分析

設計

實作

部署

維護

生命週期

需求分析階段

需求階段

定義 Model

設計階段

實作階段

實作階段

Co-work 的期間

我相信你一定曾遇這樣的情境

工程師就暴走了

所以問題發生在哪？

讓其他人分擔

撰寫 API 文件的工作

教育訓練

部署

維護 & 驗收

簡易查詢後台

實施重點

一切以 API 文件為中心

使用​統一的平台

使用版控系統

嚴格要求，照圖施工

教育訓練

權力下放

舊專案

Demo

先編寫 API definition 好處

改善 API 設計

透過工具可以儘早學習，並提供回饋。

提前測第三方 API without coding

前端團隊可以立即開始動工，不用等後端全部實作完。

可以比傳統方法更快地進行

什麼是 Swagger

使用統一的平台