使用 OAS（OpenAPI標準）來描述 Web API

無論哪種類型的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 的目標, 最基本的要對以下方面有深刻, 精準的認識: 

1. Who, 誰可以使用這個API? 

2. What, 用戶拿這個API能做什麼事?  

3. How, 用戶如何做這件事? 

4. What need, 用戶想要做這件事的話還需要什麼? 

5. 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/ 

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

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

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

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

生成代碼 

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

什麼時候使用API描述格式 

肯定是在設計接口如何表達API目標和概念, 以及數據的時候. 

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

創建OAS文檔 

建立一個products.yaml文件.  

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

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

• 第1行是Open API的版本 

• 第4行 info 的 version 是指API的版本, 而info這個版本必須使用雙引號括起來, 否則OAS解析器會把它當成數字, 從而導致文檔驗證失敗(因爲它的類型應該是字符串). 

• 第5行 paths, paths屬性應該包含該API可用的資源. 這裏面使用 {} 僅僅是爲了讓文檔驗證通過, 因爲我目前還沒有寫什麼內容. 在YAML裏, {} 表示一個空的對象, 而非空的對象則不需要這對大括號. 

描述資源 

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

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

描述資源的操作 

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

看代碼: 

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

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

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

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

在OAS文檔裏, 一個操作必須在responses屬性裏提供至少一個響應: 

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

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

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

下面我再添加一個POST Action: 

這裏還是針對 /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屬性也是可選的, 但是最好還是寫上吧, 有個描述更好. 

使用JSON Schema來描述數據 

假設一個對象有三個屬性: 編號(string), 名稱(string), 價格(number). 那麼使用JSON Schema來描述它就應該是這樣的: 

還沒完, 我還必須指出屬性是否是必填的, 然後我再加上一個remark屬性, 它不是必填的: