时间过得真快！我们发布 OpenAPI 3.0.0 已经快三年了。在此期间，我们发布了许多补丁版本，这些版本大多是轻微的澄清和更正。然而，今天有所不同。
今天，我们宣布发布 OpenAPI 3.1.0 的第一个候选版本。
闪亮的新特性
此新版本中的三个主要变化包括
- 一个新的顶级元素，用于描述在带外注册和管理的 Webhook。非常感谢 Lorna Mitchell 推动这项工作，使用我们新颖的 提案流程 并定期提醒我们专注于发布。
- 支持使用标准 SPDX 标识符识别 API 许可证。
- PathItems 对象现在是可选的，以便更轻松地创建可重用的组件库。可重用的 PathItems 可以描述在 components 对象中。还支持描述使用客户端证书保护的 API。
完美的契合
虽然这些增强功能（以及我们在 发行说明 中描述的许多其他增强功能）解决了 OpenAPI 开发者社区一些最需要的功能，但它们的光芒却被我们在 OpenAPI 3.1.0 中做出的最重要改进所掩盖。此版本的 OpenAPI 规范现在与最新 JSON Schema 草案 100% 兼容。 这项工作是 OpenAPI 开发者社区和 JSON Schema 社区成员之间共同努力的结果。特别感谢 Henry Andrews、Phil Sturgeon 和 Ben Hutton 所做的所有工作、支持和提供的耐心解释。
微小的变化带来巨大差异
对于 OpenAPI 描述的常规用户来说，3.1.0 Schema 对象的差异可能并不明显。实际上，v3.0.x 描述将非常乐意通过 v3.1.0 验证。可以逐步采用新功能。最新版本的 JSON Schema 具有许多新的功能，但我们将把这些细节留到以后的博文中讨论。
当微小的变化变得重大
在 OpenAPI v3 规范中，我们采用了 语义版本控制 来传达更改的重要性。语义版本控制是一种流行的方法，它是为管理软件包而创建的。次要版本更新表示更改是向后兼容的，而主要更新则不是。当谈论规范时，向后兼容的更改意味着什么并不明显。在 v3.0.3 中，我们 引入了语言 试图精确地说明向后兼容更改的含义。我们天真地认为这会有所帮助。
在讨论与 JSON Schema 对齐的最终细节时，我们发现 readOnly 和 writeOnly 属性存在特别棘手的问题，这些属性是在 JSON Schema 中定义的，但在 OpenAPI 中被描述为具有略微不同的行为。为了实现我们与 JSON Schema 完全对齐的目标，我们不得不放弃 OpenAPI 的行为。从技术上讲，此更改可能会“破坏”某些工具。我们还没有找到它（我们仍在寻找）。语义版本控制会坚持要求此更改表示为 4.0.0。但是，此规范更新并不是如此重大的更新，而是一些小的破坏性更改。
OpenAPI 规范的 4.0.0 版本将带来一系列预期。主要版本升级通常也会面临采用阻力。此 OpenAPI 更新不是主要更新——它有一些不错的改进，并且我们现在在 JSON Schema 上有了更好的路径，但是强迫将其升级为主要版本将导致期望不符。
这个难题导致 技术指导委员会 对此问题进行投票，因为我们第一次无法达成共识。正如你可能猜到的，最终决定是放弃语义版本控制的要求。虽然关于这是否是正确做法的意见仍然不一，但这为我们提供了未来更好地使用主要和次要版本号的空间，这些版本号更准确地传达了版本更改对大多数用户的重要性。
隆重登场！
因此，OpenAPI 3.1.0 RC0 已准备好进行最终审查，这是您在它毕业之前发表评论的邀请。在解决所有最终的收尾工作后，我们将宣布 3.1.0 完成并发布！