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 使用不同的逻辑来解析（options.setResolve(true)），而不是用于 3.0 文档的逻辑。这种逻辑旨在更加一致和可维护。 

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

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 上的开源计划。请随时查看我们的贡献指南。