Swagger 支持 OpenAPI 3.1

Swagger 推出对 OpenAPI 3.1 的支持

我们很高兴地宣布 Swagger 开源生态系统全面支持 OpenAPI 3.1。

TLDR;

🎉Swagger 现在支持编辑和渲染 OpenAPI 3.1。

Swagger 提供对 JSON Schema 2020-12 的渲染支持。

在 Swagger UI、Swagger Client、Swagger Editor (Next)、Swagger Parser、Swagger Core 和 ApiDOM 中添加了 OpenAPI 3.1 支持。

请在 swagger-api 上查看 Swagger 开源项目详细信息。

继 早期更新 和 新产品发布（其中添加了丰富的编辑和验证体验）之后，Swagger UI 现在支持渲染 OpenAPI 3.1 文档，并且广泛支持最新版本的 JSON 架构规范（草案 2020-12）。

这个里程碑伴随着新的 Swagger 编辑器 对 AsyncAPI（版本 2.*）的开箱即用支持，这意味着 Swagger 为在所有版本的 OpenAPI 和 AsyncAPI 上工作的开发团队带来了丰富的体验。

什么是 OpenAPI 3.1？

OpenAPI 3.1 是 OpenAPI 规范 (OAS) 的最新版本（在撰写本文时）。Open API 规范定义了 HTTP API 的标准、与语言无关的接口描述。它允许人类和计算机在无需访问源代码、其他文档或检查网络流量的情况下了解服务的功能。

在 OpenAPI 3.1 中，OAS 技术指导委员会 (TSC) 在社区辩论后，决定不遵循语义版本控制。这允许某些重大更改以适应与 JSON Schema 2020-12 的对齐，并将从 OpenAPI 3.0 中吸取的经验教训融入到次要版本升级中。这些更改已记录在发行说明中。

OpenAPI 3.1 中包含许多改进。对于我们来说，最突出的新增功能/更改是

• Schema 对象现在完全符合 JSON Schema 草案 2020-12，并且基本类型已更新为基于 JSON Schema 草案 2020-12。
• Webhooks 已作为顶级字段引入到 OpenAPI 对象，允许描述作为 API 一部分可用的带外注册 Webhook。
• Components 对象现在允许定义 pathItems，在 OpenAPI 文档中提升 可重用路径项对象。
• Info 对象支持在预先存在的 description 字段旁边有一个 summary 字段。
• License 对象具有新的 SPDX 许可证代码标识符字段。
• 构成有效 OpenAPI 文档的内容也发生了变化。该规范现在要求在顶层至少存在一个 paths、components 或 webhooks。以前的规范版本要求 paths。现在，有效的 OpenAPI 文档只能描述 Webhook，甚至只能描述可重用组件。

有关更改的详细列表，请查看 Mike Ralphson（OAS TSC 成员）的这篇文章。

Swagger 中的 OpenAPI 支持

以下是当前对 OpenAPI 3.0 和 3.1 的支持级别的概述。我们将很快跟进更详细的字段级别细分。

下一步是什么

接下来的重点将是弥补 OpenAPI 3.1 支持中发现的任何差距。此外，与更广泛的社区合作，以确保 OpenAPI 3.1 的最新 Swagger 功能的落实和采用。

我们致力于在广泛的 API 规范和语言中为 API 社区提供支持。在这样做时，我们计划公开我们的 Swagger 路线图，并提供有关我们最新创新的一些更新。为了透明地说明我们在各个项目中的规范支持，我们将很快公开该参考信息。

我们希望您参与我们在 Swagger 上的开源计划。请随时查看我们的贡献指南，并随时做出贡献。