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.* 版本）的开箱即用支持，可在您的 Web 浏览器中提供 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.1 版本目前通过从生成的 3.0 版本转换提供。从表示角度来看，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 版本定义时应用。任何验证错误都将像 3.0 版本一样在 SwaggerParseResult 中提供。  

处理 OpenAPI 3.1 规范时，Swagger Parser 使用与 3.0 文档不同的逻辑来解析 (options.setResolve(true))。这种逻辑旨在更具一致性和可维护性。  

有关 Swagger Core 和 Swagger Parser OpenAPI 3.1 支持的完整详细信息，请查看 GitHub 维基。  

OpenAPI 3.1 的渲染功能将很快作为我们的 Swagger UI 增强功能的一部分推出。简而言之，通过将 ApiDOM 与 Swagger Client 集成，将实现在 Swagger UI 中处理和渲染 OpenAPI 3.1 定义/文档的能力。  

我们预计这将在 2023 年第一季度完成，届时渲染功能也将引入到我们的 Swagger Editor 工具中。  

OpenAPI 3.0 和 3.1 支持概述  

以下是当前 OAS 3.0 和 3.1 支持程度的概述。我们将很快提供更详细的字段级别分解。  

后续步骤  

我们致力于支持 API 社区，涵盖各种 API 规范和语言。  

在此过程中，我们将公布 Swagger 路线图，并提供一些最新创新的更新。此外，我们希望在项目中的规范支持方面保持透明，因此很快将公开相关参考信息。  

我们非常希望您能参与到 Swagger 的开源项目中。请随意查看我们的贡献指南。