無論哪種型別的Web API, 都可能需要給其他開發者使用. 所以API的開發者體驗是很重要的. API的開發者體驗, 簡寫為 API DX (Developer Experience). 它包含很多東西, 例如如何使用API, 檔案, 技術支持等等, 但是最重要的還是API的設計. 如果 API 設計的不好, 那么使用該API構建的軟體就需要增加在時間,人力,金錢等方面的投入. 有時候API會被錯用, 甚至帶來毀滅性后果. 最后抱怨該API等用戶越來越多, 慢慢的, 客戶就會停止使用該API.

API的目的是讓人們可以簡單的使用它來達到自己的目的. 目前行業內有很多API風格, 例如: REST, gRPC, GraphQL, SOAP, RPC等等. 但是每個風格都遵循一些基本的設計原則.

用戶就是上帝, 為用戶設計API

和構建任何東西一樣, 你需要一個計劃, 你需要在真正做之前來決定你想要的是什么. API 設計也是一樣的.

API 并不是用來盲目的暴露一些資料或業務處理能力. 它就像我們每天使用的任何形式的介面一樣, 例如微波爐的操作按鈕, 是來幫助用戶完成他們的目標的. 所以需要從用戶的視角來決定一個API的設計目標. 在整個設計程序中, 必須牢記以用戶的視角去設計, 如果以開發者的角度去設計, 那么問題就大了.

如果以開發者的視角去設計的API, 那么通常的后果是開發出的API會很注重功能實作的程序和原理, 而不是用戶如何能簡單平滑的使用這個API來達到他們的目的. 所以一定要注重用戶的需求, 而不要讓內部實作細節, 原理什么的來騷擾用戶. 最后再次強調, 要設計出讓用戶容易理解和容易使用的API.

所以 API 就是用戶看到的, 它表示出用戶能使用它做什么. API 的實作細節, 也就是如果完成的該功能的細節, 需要對用戶隱藏.

識別 API 的目標

記住首先考慮用戶的感受之后, 下面就需要考慮用戶能拿它來做什么了, 也就是識別API的目標.

識別 API 的目標, 最基本的要對以下方面有深刻, 精準的認識:

Who, 誰可以使用這個API?
What, 用戶拿這個API能做什么事?
How, 用戶如何做這件事?
What need, 用戶想要做這件事的話還需要什么?
What return, 用戶會得到什么?

1.就是指API的用戶, 4,5分別表示輸入輸出.

針對2, 3解釋一下

通常針對2.What(用戶拿API能做什么)可以導致(分解)多個3.How(多個步驟), 這樣的話每個步驟就是一個API的目標.

比如說, 用戶想去淘寶買一個商品, 那么怎么買? 首先需要把商品添加到購物車, 然后再結賬. 那么這個API就應該有兩個目標: 添加商品到購物車, 以及結賬.

如果不這樣分解到話, 通常設計出的API會缺失一些目標.

針對1, 也解釋一下

首先應該識別出不同種類的用戶, 這里的用戶可能是人, 也可能是其他的程式. 通常通過檢查輸入和輸出就可以識別出用戶.

總結一下就6個方面:

用戶
能做什么
如何做 - 分解步驟
輸入
輸出
目標

避免從開發者角度設計API

這部分包含幾個方面. 包括:

開發者所在公司的組織結構(參考康威定律)
資料, 例如資料使用了開發者所在公司內部的一些專有術語, 或者干脆把內部資料庫模型暴露了出來.
不要暴露實作細節, 避免受到業務邏輯實作細節的影響
避免受到軟體架構的影響, 比如說在開發者公司內部查詢產品名稱和產品價格是兩個API, 那么給用戶使用的API必須整合一下, 不能讓用戶分兩步查詢.

最重要的還是要時刻牢記, 你所設計的這些東西都是用戶真正需要的嗎?

下面切入正題:

使用API描述格式來描述API

這里我以RESTful風格的API為例. 想要了解使用ASP.NET Core 3.x 構建 RESTful API, 這里有一個教程(但是還沒講完) https://www.bilibili.com/video/av77957694/.

很多人使用Excel或者紙和筆來進行API的設計作業. 但是如果想要在設計階段精準描述一個API, 尤其是它的資料, 那么最好使用一個結構化的工具, 例如API描述格式.

API描述格式會為API提供一個標準化的描述, 并且它很像代碼. 它的優勢主要有:

有助于在專案團隊中共享設計
了解這種格式的人或者工具可以很簡單的理解它.

針對REST而言, OpenAPI Specification(OAS) 就是一個非常流行API描述格式規范.

OAS

API描述格式是一種資料格式, 它的目標就是描述API.

而OAS (OpenAPI Specification)是一個與編程語言無關的REST API描述格式. 它是由 OAI (OpenAPI Initiative) 所提倡的. OAI 是Linux基金會下面的一個組織, 專注于提供與供應商無關的描述格式. 而OAS則是社區驅動的一種格式, 任何人都可以做貢獻.

OAS vs Swagger

OAS 原來叫 Swagger Specification, 2015年11月這個格式被貢獻給了OAI, 并在2016年1月更名為 OpenAPI Specification. Swagger 規范最后的2.0版本就變成了 OpenAPI 2.0. 目前最新的OAS 應該是3.0大版本

YAML

OAS檔案可以使用YAML或JSON格式, 我使用YAML.

像寫代碼一樣描述API

OAS檔案就是一個文本檔案, 可以納入版本控制系統 ,例如 Git等. 所以在設計迭代的時候很容易進行版本管理和變化追蹤.

編輯器

OAS有一個在線的專用編輯器: http://editor.swagger.io/

@Swagger Ed
itor.
File ,
Edit
Generate Server
Generate Client
1
2
3
4
5
6
7
8
9
10
11
12
13
14
16
17 -
18
19
21
23
24
25
26
27
28
29
30
SMARTBEAR
Swagger:
"2.0"
info:
description:
more about
"This is a sample server Petstore server. You can find out
Swagger at Chttp://swagger.io](http://swagger.io) or on
Circ. freenode.net, #swagger](http://swagger.io/irc/).
For this
sample, you can use the api key ?special-key'
fi Iters . "
version:
"1.0.0"
title: "Swagger Petstore"
terms0fService :
"http : //swagger. io/terms/"
to test the authorization
1.0.0
Swagger Petstore
[ Base URL: petstore . swagger. io/v2 J
This is a sample server Petstore server. You can find out more about Swagger at bttp://swagger.io or on
irc.freenode.net, #swagger. For this sample, you can use the api key special—key to test the
contact:
emai I :
" apitean@swagger.10
license:
name: "Apache 2.0"
url:
host: "petstore . swagger. io"
basePath: "/v2"
tags :
"pet"
15- - name:
" http : //www.apache.org/licenses/LICENSE-2. O. html "
description: "Everything about your Pets"
external Docs:
description: "Find out more"
"http : //swagger. io"
url:
20- - name: "store"
description: "Access to Petstore orders"
22 ? - name: "user"
description: "Operations about user"
external Docs:
description: "Find out more about our
url:
"http : //swagger. to"
schemes :
"https"
"http"
naths:
authorization filters.
Terms of service
Contact the developer
Apache 2.0
Find out more about Swagger
Schemes
HTTPS
pet Everything about your Pets
Authorize
Find out more: http://swagger.io
store"
POST
PUT
/ pet
/pet
Add a new pet to the store
Update an existing pet

左邊是代碼編輯區域, 右邊是渲染結果.

但是我更習慣于本地編輯器, 我使用VSCode, 并安裝 Swagger Viewer 和 openapi-lint 兩個插件.

EXPLORER
v OPEN EDITORS
GROUP 1
{O one.yaml
GROUP 2
x Swagger Preview
v OAS
{n} one.yaml
{O product.yaml
{n} one.yaml X
{O one.yaml > { } paths > (products > { }
Swagger Preview - /Users/solenovex/OAS/one.yaml
post > { }
responses > { }
or
200 >
- /Users/solenovex/OAS...
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
openapi: 3. ?.?
info:
title: "Shopping API"
version
: "l.?.???
paths:
/products:
description: The products catalog
get:
summary: Sea rch for products
description: I
Search for products in catalog
using a free query parameter
parameters:
— name: free—query
description: I
A product 's name, reference,
partial description
in: query
required: false
schema :
type: string
responses:
description: I
desc
Swagger
SMARTBEAR
Shopping API
default
I.o.o
OAS3
GET
POST
/products Search for products
/ products Add P roduct
Products matching free query parameter
content:
application/json:
schema :
type: array
description: Array of products
items :
type: object
description: A product
required:
reference
— name

共享API描述, 對API進行檔案記錄

OAS檔案可以用來生成API對參考檔案, 這個參考檔案可以展示出所有可用的資源以及相應的操作. 通常我會使用Swagger UI, 它就是上圖右側的部分.

生成代碼

使用API描述格式進行描述的API, 其代碼也可以部分生成. 通常是一個代碼骨架.

什么時候使用API描述格式

肯定是在設計介面如何表達API目標和概念, 以及資料的時候.

使用OAS來描述REST API的資源以及Action

創建OAS檔案

建立一個products.yaml檔案.

然后在里面輸入 api 或 open等字串, 會出現兩個提示選項:

products.yaml
1
api
openapi, OpenAPI 3.0 lintable
openapi, OpenAPI 3.0 minimal
OpenAPI 3.0 minimal O

先選擇下面那個選項, 其結果是:

products.yaml > { } paths
1
2
3
4
5
openapi: 3.?.?
info:
title: "API"
versxon 1
paths:

第1行是Open API的版本
第4行 info 的 version 是指API的版本, 而info這個版本必須使用雙引號括起來, 否則OAS決議器會把它當成數字, 從而導致檔案驗證失敗(因為它的型別應該是字串).
第5行 paths, paths屬性應該包含該API可用的資源. 這里面使用 {} 僅僅是為了讓檔案驗證通過, 因為我目前還沒有寫什么內容. 在YAML里, {} 表示一個空的物件, 而非空的物件則不需要這對大括號.

描述資源

為了描述products這個資源, 就需要填寫paths屬性:

1
2
3
4
5
6
7
openapi: 3.?.?
info:
title: "API"
version
paths:
/products:
description: FR51J*l

這里description屬性不是強制的, 但是它可以用來描述該資源.

描述資源的操作

OAS檔案里描述的資源肯定包含一些操作, 否則檔案就不合理.

看代碼:

1
2
3
4
5
6
7
8
9
10
11
12
3.?.?
info:
title: "API"
version: "l.?.?"
paths:
/products:
description:
get:
summa ry:
description: I

我為/products這個資源添加了一個GET Action (get屬性), 然后我對這個get也進行了描述.

summary相當于是對這個Action的一個概括性描述, 而description則能提供更詳細的描述資訊.

這里description是支持多行文本的, 但是在YAML里面要想支持多行文本, 那么string屬性必須以 | 管道符開頭.

注意, 這里第1行 openapi下面的波浪線表示檔案驗證失敗.

在OAS檔案里, 一個操作必須在responses屬性里提供至少一個回應:

1
2
3
4
5
6
7
8
9
l?
11
12
13
14
15
16
17
openapi: 3.?.?
info:
title: "API"
version: 1
paths :
[products:
description:
get :
summary:
description: I
responses:
"2???? :
description: I

一個Action可能有多種回應結果, 每種可能的回應結果都要在responses屬性中描述.

每個回應都以狀態碼進行標識, 并且必須包含一個description屬性.

注意: 狀態碼數字必須用雙引號括起來, 因為它的型別本應該是字串, 而這里的200是一個數字.

下面我再添加一個POST Action:

1
2
3
4
5
6
7
8
9
l?
11
12
13
14
15
16
17
18
19
2?
21
22
23
24
25
26
openapi: 3 .?.?
info:
title: "API"
? "1.0.0"
versxon :
paths :
/products :
description: FR51J*
get :
summary:
description:
responses :
"2???? :
description: I
post:
summary:
description:
responses :
"2???? :
description: I

這里還是針對 /products 這個資源, 我就不過多解釋了.

使用OpenAPI 和 JSON Schema 來描述 API 的資料

OAS 依賴于 JSON Schema 標準來對所有的資料(查詢引數, body 引數, 回應body等)進行描述.

注意, OAS 使用的其實是JSON Schema的一個子集, 并不包含所有的 JSON Schema 特性, 并且還添加了一些 OAS 獨有的特性到這個子集里.

描述查詢引數

如果我們的get操作里需要一些查詢引數(查詢字串, Query String), 那么可以使用 parameters 這個屬性:

這里 parameters屬性是一個集合或陣列, 每個集合元素使用 - 開頭.

為了描述一個引數, 至少需要name, in 和 schema 三個屬性. 在本例中, 還包含 required 和 description 兩個可選的屬性.

in表示引數的位置, 這里值為query, 表述它是查詢字串(Query String, 例如 api/products?searchTerm=xxx).
required 為 false 表示不是必填引數. required是可選的, 如果沒有寫的話, 那么它的值就是false. 但是最好還是寫上required屬性.
它的資料結構使用schema屬性來表示, 這里就是一個簡單的字串型別. 但是它其實是一個JSON schema, 所以它可以是復雜的物件型別.
description屬性也是可選的, 但是最好還是寫上吧, 有個描述更好.