最新版本的 OpenAPI 規格，OpenAPI 3.0 (OAS 3.0)，於去年發布，並且已經獲得 API 開發人員和希望在 OAS 上標準化的組織採用。
OAS 3.0 是自該規格捐贈給 OpenAPI Initiative，並於 2015 年從 Swagger 規格重新命名為 OpenAPI 規格以來，首次發布的主要版本。
在去年年底，我們有機會與 OpenAPI Initiative 的兩位成員 Ron Ratovsky（OAI 技術指導委員會成員，也是 SmartBear 的 Swagger 開發人員福音傳道者）和 Ole Lensmar（OAI 董事會主席）一起討論 OAS 3.0 的最新功能和增強功能。
在這 60 分鐘的簡報中，演講者分享了他們對規格如何重組、他們最期待的新功能，以及 API 團隊如何開始轉向 OAS 3.0 的見解。
我們討論的完整影片在此處提供。但我們也希望提供更詳細的分解，包含簡報的片段和重點。
在本文中，我們將分享最新版本 OAS 的一些主要更新，並分解您在轉換到 OAS 3.0 時需要了解的內容。
簡化的結構，具有更高的重複使用性
OAS 3.0 引入了一種新的、更簡化的結構。新的結構旨在讓編寫和瀏覽 OAS 定義更容易 — 結合 OAS 2.0 的一些現有物件、標準化用於規格不同部分的命名，甚至引入新物件以擴展 OAS 3.0 內的重複使用性。
可重複使用的元件數量從 4 個增加到 9 個，新增了 連結和 回呼等新功能，我們將在本文後面更詳細地介紹。
了解更多
閱讀文件： OpenAPI 3.0 結構
內容協商支援
OAS 3.0 對於如何定義請求和回應的 body 引入了一些變更。一個重大變更是 body 和 formdata 參數已移除，並替換為 requestBody。requestBody 更具彈性，因為它允許您使用不同的媒體類型，例如 JSON、XML、表單資料、純文字和其他類型，並針對不同的媒體類型使用不同的結構描述。
其他重大變更，包括
- 操作現在可以同時使用表單資料和其他媒體類型，例如 JSON。
- consumes 陣列已替換為 requestBody.content 對應，它將媒體類型對應到它們的結構描述。
- 結構描述可能會因媒體類型而異。
- 表單資料現在可以包含物件，您可以指定物件和陣列的序列化策略。
了解更多
閱讀文件： 描述請求主體
增強的安全性定義
雖然 OAS 3.0 中的安全性定義結構與 OAS 2.0 保持一致，但有一些重要的變更會影響您描述安全性流程的方式。最值得注意的變更之一是 OAuth 2 流程已重新命名以符合 OAuth 2 規格：accessCode 現在為 authorizationCode，application 現在為 clientCredentials。
其他變更包括
- securityDefinitions 已重新命名為 securitySchemes，並移至 components 內。
- type: basic 已替換為 type: http 和 scheme: basic。
- 新的 type: http 是所有 HTTP 安全性方案的總稱類型，包括基本、Bearer 和其他，而 scheme 關鍵字表示方案類型。
- API 金鑰現在可以傳送 in: cookie。
- 新增支援 OpenID Connect Discovery (type: openIdConnect)。
- OAuth 2 安全性方案現在可以定義多個流程。
了解更多
閱讀文件：身份驗證和授權
更新的參數類型
如先前所述，OAS 3.0 移除了兩個參數類型：body 和 formdata。OAS 3.0 還引入了一種新的參數類型 cookie，這是記錄目前使用 Cookie 的 API 所要求的更新。
OpenAPI 3.0 還包括支援操作參數中的陣列和物件，並允許您指定這些參數應如何序列化。序列化方法由 style 和 explode 關鍵字定義
- style 定義多個值的分隔方式。可能的樣式取決於參數位置 — path、query、header 或 cookie。
- explode（true/false）指定陣列和物件是否應為每個陣列項目或物件屬性產生個別參數。
OpenAPI 序列化規則基於 RFC 6570 定義的 URI 範本模式的子集。
了解更多
閱讀文件： 描述參數
改進的範例
範例是記錄 API 的重要部分。OAS 3.0 包含了如何規格內使用範例的重大改革，包括描述多個範例、在 API 定義中重複使用範例，以及參考外部範例的能力。
範例的變更提供了在使用範例物件時更高的重複使用性。
了解更多
閱讀文件：新增範例
介紹 OpenAPI 連結
連結是 OpenAPI 3.0 的新功能之一。連結在 API 設計階段引入了一個全新的概念，用於在設計 API 時顯示回應和操作之間的關係。
使用連結，您可以描述一個操作傳回的各種值如何用作其他操作的輸入。這樣，連結會在操作之間提供已知的關係和遍歷機制。連結的概念經常與超媒體進行比較，但 OpenAPI 連結不需要實際回應中存在連結資訊。
閱讀文件： OpenAPI 連結
支援描述回呼
OAS 3.0 支援描述回呼，可用於定義非同步 API 或 Webhook。回呼可讓您處理您的服務為回應某些事件而傳送給其他服務的請求。這有助於改善 API 向用戶端提供的工作流程。
回呼使用與其他路徑定義相同的結構，並讓您描述用戶端為了使 Webhook 正常運作而應實作的內容。
閱讀文件： 回呼
OAS 3.0 的其他變更
除了 OpenAPI 3.0 的一些主要變更之外，還有一些額外的更新在轉換到 OAS 3.0 時需要了解。
- OAS 3.0 從 GitHub Flavored Markdown (GFM) 轉為支援 CommonMark。
- 擴展 JSON Schema 支援，包括
anyOf、oneOf 和 not。
- 定義多個伺服器和範本伺服器定義
- 新增對 TRACE 方法的支援
從 OAS 2.0 到 OAS 3.0 的重大變更
如果您準備開始轉換到 OAS 3.0，有一些工具可以協助您重組現有的定義。SwaggerHub 提供內建的轉換器，可將您現有的規格轉換為 3.0 友善的格式，讓您輕鬆上手。
開始轉換過程時，還有一些重要的領域需要關注
- 定義、參數、回應和 securityDefinitions 都移至 components 之下
- Schemes、hosts 和 basePaths 已被 servers 取代
- 參數需要重新架構
- 類型定義移至 schema 之下
- Body 和 formdata 參數提取至 requestBody
- 回應需要重新架構
- 一些安全性定義變更
- 'basic' 變更為 'http'
- OAuth2 流程已重新命名，並給予略有不同的結構
OAS 3.0 的其他資源
您可以使用開源的 Swagger Editor 和 Swagger UI，或在 SwaggerHub 平台中開始使用 OAS 3.0 設計和記錄 API。我們也整理了一些我們最喜歡的 OAS 3.0 資源，以幫助您入門