Darrel Miller

我们很高兴地宣布 ASC 2020 的两位主题演讲嘉宾，他们将在 9 月 9 日至 10 日通过虚拟方式来到您的沙发旁。

Lorna Mitchell，多语言软件开发人员和开发者关系专业人士，将加入我们，分享她丰富的智慧。Lorna 深厚的 API 经验以及她幽默地提醒我们截止日期让我们忘记的最佳实践的能力，保证了本次会议将是时间价值最大化。

Mark Nottingham 这个名字对于许多发现自己需要阅读 IETF 规范来解决 API 问题的人来说一定很熟悉。无论您需要格式化错误负载、解析 URI 模板，还是就知名 URL 的相对优势进行辩论，Mark 都是一个拥有多年经验的理性意见宝库。

加入我们 https://apispecs.io，您的 API 会感谢您这么做的。

时间过得真快！我们发布 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 完成并发布！