OpenAPI 驅動的 API 設計

Keshav Vasudevan

2018 年 4 月 24 日

在我之前的文章中，我詳細說明了使用 OpenAPI 規格 (OAS) 進行定義驅動開發的重要性，並承諾會繼續發表更多文章，詳細說明OpenAPI 規格如何協助您 API 生命週期的各個方面。

在本系列的第二篇文章中，我將深入探討了解 OAS 如何在您的 API 生命週期的第一階段：API 設計中幫助您。

什麼是 API 設計？

好的設計是紀念碑成為奇觀的原因，也是產品變得偉大的原因。從紀念碑到艾菲爾鐵塔，再到像這些酷炫的飲用吸管等產品，設計可以是實現出色可用性和採用的基礎。

在 API 的世界中，設計可以被認為是伺服器和用戶端之間合約的建模。在之前的文章中，我給出了以下 API 設計的定義

「設計 API 意味著提供有效的介面，協助 API 的使用者更好地了解、使用和整合它們，同時協助您有效地維護它。每個產品都需要使用手冊，您的 API 也不例外。」

原始「Swagger」規格的創建者 Tony Tam 解釋說，設計 API 涉及「規劃失敗」。API 合約協助內部和外部的利害關係人了解該做什麼，以及如何更好地協同工作以建置出色的 API。

使用 OAS 3.0 設計 API

OpenAPI 規格是設計 API 最著名的方法之一。OAS 指定描述 API 介面所需的規則和語法。在撰寫本文時，我們正處於 OAS 的第三個版本。OAS 不斷發展以滿足現代 API 團隊的需求，並不斷推出更新以簡化規格的使用，並使人類和電腦更容易理解。這是使用 OAS 3.0 定義的 OAS API 的一般大綱

上圖將 OAS 設計的 API 合約中的各個部分分解開來。起初可能看起來令人困惑，但讓我分解每個部分的含義以及如何使用它。

資訊

資訊區段包含與 API 合約關聯的中繼資料。此區段的必要部分是 API 的標題、版本和描述。此區段還可以包含其他欄位，例如聯絡資訊、授權資訊和服務條款連結。基本上，資訊物件應讓您的使用者和內部開發人員大致了解您的 API 的用途。

openapi: 3.0.0

info

title: 簡單寵物商店

version: 1.0.0

description: 這是一個寵物商店的範例伺服器。

termsOfService: http://example.com/terms/

contact

name: API 部落客

email: [email protected]

url: http://example.com/support

license

name: Apache 2.0

url: http://www.apache.org/licenses/LICENSE-2.0.html

在此處閱讀完整文件。

伺服器

您的 API 是使用者和您伺服器之間的合約。伺服器物件可以透過其 URL 為您的用戶端提供有關 API 伺服器位置的資訊。與僅允許 API 定義具有一個伺服器 URL 的規格 2.0 版本不同，OAS 3.0 支援多個伺服器。這很有用，因為在現實世界中，API 存在於多個環境中，而且合約的業務邏輯可能會因環境而異。

此區段的範例如下 -

servers

- url: http://production.example.com/v1

description: 生產伺服器

- url: http://staging.example.com

description: 用於測試的暫存伺服器

在此處閱讀完整文件。

安全性

在當今資料敏感的世界中，每個 API 都需要某種程度的安全性。OpenAPI 描述格式支援各種身份驗證和授權方案，以防止不明、未註冊的使用者存取 API。OpenAPI 支援

HTTP 身份驗證方案
標頭、Cookie 或查詢字串中的 API 金鑰
OAuth2
OpenID

在您的 API 設計中實施安全性有兩個步驟。第一步是定義安全性實作，第二步是呼叫它們。本區段中定義的安全性物件用於呼叫實際的安全性定義。安全性實作的定義在元件區段中完成，本文稍後會詳細介紹。

這是安全性物件的範例

security

- ApiKeyAuth: []

- OAuth2

- read

- write

components

ApiKeyAuth

type: apiKey

in: header

name: X-API-Key

在上面的範例中，ApiKeyAuth 在安全性物件下呼叫，但該物件的實際定義應在元件物件下完成。

在此處閱讀有關安全性物件的更多資訊。

路徑

本區段顯示您的 API 公開的各個端點，以及對應的 HTTP 方法。實際的要求-回應週期也在每個方法下詳細說明。要求由參數物件描述，回應由回應物件描述。

您可以在此處閱讀有關路徑和操作的更多資訊。

參數

參數是您要求的變數部分。您可以使用 OAS 3.0 指定四種類型的參數

路徑參數，例如 /users/{id}
查詢參數，例如 /users?role=admin
標頭參數，例如 X-MyHeader: Value
Cookie 參數，這些參數在 Cookie 標頭中傳遞，例如 Cookie: debug=0; csrftoken=BUSe35dohU3O1MZvDCU

回應

回應是根據要求傳回的物件。每個回應都由其 HTTP 狀態碼和傳回的資料定義。使用的 HTTP 狀態碼定義要求是否成功。若要查看 HTTP 狀態碼清單，請在此處閱讀。

以下是簡單回應的範例

responses

200:

description: 成功回應

content

text/plain

schema

type: string

example: 範例字串在此

在此處閱讀有關回應的更多資訊。

元件

隨著您針對 API 公開更多資源和操作，合約可能會變得非常長。您的 API 可能會在許多不同的路徑和操作中重複許多現有的參數或回應描述，每次都重新編寫它們會使它們容易出現不一致的描述，而且非常耗時。

元件物件可以保留一組 API 設計的可重複使用物件。可重複使用的物件可以是結構描述、回應、參數、範例等。然後可以在任何路徑項目中參考確切的可重複使用元件。

以下是元件物件的範例

paths

/pet

get

summary: 取得所有寵物

responses

'200':

description: 所有寵物的清單

content

application/json

schema

type: array

items

$ref: '#/components/schemas/Pet'

components

schemas

Pet

type: object

properties

id

type: integer

example: 65

name

type: string

example: doggo

age

type: integer

example: 4

在此處閱讀有關元件的更多資訊。

外部文件

任何您能提供的額外資訊，以利於您的 API 更容易被使用和整合，都是個好主意。OAS 3.0 允許您參考外部文件。

描述：其他資訊可以在這裡找到

網址：http://info.here.com

當然，這僅是對與 OpenAPI 設計的 API 相關的各個區段的概述。設計是主觀的，雖然 OAS 為您提供了描述 API 所需的規則和項目，但您如何使用它們有效地傳達 API 的價值才是造就卓越設計的原因。我過去曾介紹過 API 設計的良好實踐，所以請查看一下，並告訴我您的想法。

如果您想了解 OAS 3.0 相較於 2.0 的新功能，請觀看此錄製的培訓，如果您只是想學習如何開始使用 OAS，您可以隨時使用此影片作為參考。

API 設計的合適工具

設計可能是 API 生命週期中最重要的一個方面，因此需要一個專用的工具。Swagger 的 OpenAPI 編輯器可能是您開始 API 設計過程的好方法。它乾淨、高效，並配備許多功能，可協助您直接設計 RESTful 介面。

該編輯器適用於任何開發環境，無論是本地還是網頁版
當您編寫時，使用簡潔的回饋和錯誤處理來驗證您的 OpenAPI 相容語法
在您仍然定義 API 的同時，以視覺方式呈現您的 API 規格並與您的 API 互動

如果您想與您的 API 設計進行協作，您可以隨時嘗試SwaggerHub。SwaggerHub 是一個 API 開發平台，供團隊以一致和標準化的方式設計 API。Swagger 工具生態系統與 OAS 相結合，可以將您的 API 設計提升到新的層次。

感謝您的閱讀！正在尋找更多 API 資源嗎？訂閱 Swagger 電子報。每月收到一封電子郵件，其中包含我們最佳的 API 文章、培訓、教學等。 訂閱

OpenAPI 驅動的 API 設計

什麼是 API 設計？

使用 OAS 3.0 設計 API

資訊

伺服器

安全性

路徑

參數

回應

元件

外部文件

標籤

API 設計的合適工具