Swagger 對於 OpenAPI 3.0 和 OpenAPI 3.1 的支援

在 Swagger Editor 最新版本的近期推出之後，我們很高興宣布它包含對 OpenAPI 3.0 中編輯和渲染體驗的廣泛支援。 

Swagger 生態系統一直在忙於開發 OpenAPI 3.1 的支援。OpenAPI 3.1 是 OpenAPI 規格的最新版本。  

現在，新編輯器支援豐富的編輯體驗，涵蓋諸如特定語言的文件、更好的自動完成、驗證、語法醒目顯示、跳至參考和在 OpenAPI 3.0 和 3.1 中「尋找符號」等功能。OpenAPI 3.1 的渲染將很快成為Swagger UI 增強功能的一部分。 

最新版本同時也支援新編輯器對AsyncAPI（版本 2.*）的開箱即用支援，在您的網頁瀏覽器中提供跨 OpenAPI 和 AsyncAPI 的豐富編輯體驗。 

此外，以下是關於整個 Swagger OSS 專案套件中 OpenAPI 規格 (OAS) 3.1 支援的快速更新。 

Swagger Core 2.2.0 版本在表示、(反)序列化以及註釋和程式碼優先規格解析的部分支援方面引入了對 OpenAPI 3.1 / JSON Schema 2020/12 的支援。OAS 3.1 支援已添加到目前提供 OAS 3.0 支援的同一程式碼行中。  

Swagger Core 和 Parser 的主要分支，產生以下成品： 

• io.swagger.core.v3:swagger-core:2.2.x 
• io.swagger.parser.v3:swagger-parser:2.1.x 

截至撰寫本文時，程式碼優先 OAS 3.1 規格解析和註釋的支援正在進行中，目前透過從產生的 3.0 轉換來提供 3.1。從表示的角度來看，swagger-models 提供 OpenAPI 3.x 定義的 POJO 表示。 

Swagger Parser（自然地）將 OpenAPI 規格剖析為 Swagger Core 的 swagger-models 模組提供的 OpenAPI 實例。自 2.1.0 版本以來，它支援使用與 OAS 3.0 相同的 API 來剖析和驗證 OpenAPI 3.1 規格。  

它透過檢查 OpenAPI 欄位的值來偵測版本： 

    SwaggerParseResult result = new 
    OpenAPIParser().readLocation("./path/to/openapi31.yaml", null, null);  
    OpenAPI = result.getOpenAPI();
    

傳回的 OpenAPI 實例將類似於 Swagger Core 反序列化所獲得的實例。 

由於 Swagger Parser 2.1.0 版，驗證也支援 OAS 3.1 規格規則，當透過 OpenAPI 欄位偵測到版本 3.1 定義時，將套用這些規則。任何驗證錯誤都將與 SwaggerParseResult 中 3.0 的錯誤一樣提供。 

在處理 OpenAPI 3.1 規格時，Swagger Parser 使用與 3.0 文件不同的邏輯來解析 (options.setResolve(true))。這種邏輯旨在更一致且更易於維護。 

有關 Swagger Core 和 Swagger Parser OpenAPI 3.1 支援的完整詳細資訊，請參閱 GitHub wiki。 

OpenAPI 3.1 的渲染將很快成為我們Swagger UI 增強功能的一部分。簡而言之，在 Swagger UI 中處理和渲染 OpenAPI 3.1 定義/文件的能力將透過 ApiDOM 與 Swagger Client 的整合來實現。 

我們預計將在 2023 年第一季完成此功能，這也將把渲染功能帶入我們的 Swagger Editor 工具中。 

OpenAPI 3.0 和 3.1 支援概述 

以下是目前對 OAS 3.0 和 3.1 的支援程度概述。我們將很快提供更詳細的欄位層級分解。 

後續步驟 

我們致力於在 API 規格和語言的各個領域為 API 社群提供支援。  

在這樣做的同時，我們將開放 Swagger 路線圖，並提供有關最新創新的一些更新。此外，我們希望在我們的專案中保持規格支援的透明度，因此將很快提供參考資訊。 

我們希望您能參與我們在 Swagger 中的開源倡議。請隨時查看我們的貢獻指南。