跳至主要内容

新年新规范

作者 2017 年 1 月 24 日博客

这是一段激动人心的旅程,我们很高兴地宣布 OpenAPI 规范版本 3.0 即将发布!

Image from the most recent Meeting of the Open API Initiative Technical Developer Community Meeting

来自最近一次 OpenAPI Initiative 技术开发者社区会议的图片

在过去的一年里,技术开发者社区 (TDC) 筛选了数百个工单和数千条评论 - 所有这些都是为了整合社区成员的需求,并改进 2.0 规范以服务于他们。我们倾听、辩论、达成一致,也出现分歧,但始终坚持让规范保持简单、实用,同时又功能强大。下一个重要里程碑将是第一个实现者草案,它将于 **2017 年 2 月 28 日** 发布。

变更

在过去几个月里,我们通过一系列博客文章、演讲,以及当然,规范本身的变更,宣布了规范即将发生的变更。以下是一些最显著变更的简要回顾。

  • 重新排列了规范的结构,以方便和扩展可重用性。
  • 扩展了 JSON Schema 支持,以包含 `oneOf`、`anyOf` 和 `not` 支持。
  • 更改了参数结构,以允许在参数中使用 schema。
  • 添加了对 Cookie 参数的支持,并消除了 dataForm 参数。
  • 主体参数被提取到它们自己的实体中。
  • 添加了对内容类型协商的支持。
  • 引入了一种新格式,允许在响应和未来请求之间进行静态链接。
  • 简化和增强了 API 的安全定义。
  • 添加了一种回调机制来描述 WebHooks。

为了帮助工具开发人员,我们还承诺对规范进行语义版本控制。这意味着对规范的任何更改都将触发版本更新,从而更易于管理和控制。

实现者草案

经过如此多的工作投入到规范中,现在是开发人员开始在现实世界场景中证明其用途的时候了。因此,这个实现者草案是通往最终版本的重要一步。随着更广泛的受众提供反馈,以及任何由此产生的问题得到解决,它将引导我们走向最终发布。今天,我们呼吁您开始使用该规范,并帮助我们确保它能够实现其目标并达到最高质量。

下一步

这也意味着规范的重大更改将不再引入。这并不意味着规范已经完全准备就绪,但我们已经开始专注于清理文档,以帮助使新的规范更容易理解。

因此,在接下来的几周内,TDC 将专注于关闭已解决的工单并标记未来版本的工单。我们还将验证规范是否包含所有必要的信息,包括必要的说明和示例。

作为社区成员(是的,您!),请查找任何标记为 '需要帮助' 的工单,这些工单表明需要帮助解决未解决的问题。与往常一样,请随时提交额外的工单和 PR,无论版本状态如何。