OpenAPI 规范 3.1.0 发布

来源: OSCHINA
2021-02-20

OpenAPI Initiative 宣布发布 OpenAPI 规范 3.1.0。OpenAPI 规范是用于描述 API 的行业标准,它允许开发人员和计算机在不需要访问源代码、文档或网络流量的情况下理解 API 的功能。

3.1.0 中的更新内容包括有:与 JSON Schema 的最新草案兼容、用于描述 Webhooks 的新的 top-level element、以及对使用 SPDX 标识符识别 API 许可证的支持。此外,PathItems object 现在是可选的,这使得创建可重用的组件库更加简单。完整更新内容如下:

Additions

  • 添加了jsonSchemaDialect顶层字段,允许为 Schema Objects 定义一个默认的 $schema 值。

Updates

  • 将一些链接更新到更准确的位置。
  • 将 JSON Schema 支持更新为最新的 2020-12 草案
  • 修订了 URI 和 URL下 的 relative reference resolution。
  • 重新设计了文件上传描述,以考虑到新的 JSON Schema 功能。这包含了 breaking changes。
  • 规范扩展的 x-oai- 和 x-oas- 前缀现在都保留给 OpenAPI Initiative 定义。

Clarifications

  • Path 参数值不能包含非转义字符/?#
  • 进一步解释 Reference Object 和 JSON Schema 的引用应该用在哪里。
  • 当值是 URLs/URIs 时,Unified wording。
  • 重写了 Path Item 的 $ref,以考虑到引用和组件的变化。
  • 修复了一些例子。
  • 较小的文本更改以提高一致性和可读性。
  • Reference Object 的描述已更新,以进一步阐明其行为。
  • 进一步更新了 Schema Object 的描述,以考虑到最新的草案,以及默认使用 https://spec.openapis.org/oas/3.1/dialect/base 作为默认的 OAS 方言。
  • 将“Schema Vocabularies”改为“Schema dialects”。

除了发布版本 3.1.0,OpenAPI Initiative 还宣布赞助了新文档的创建。以帮助用户更容易、更好地理解 OpenAPI 规范的结构及其优势。

目前,OpenAPI 规范已被世界各地的组织所使用,包括 Atlassian、Bloomberg、eBay、Google、IBM、微软、Oracle、Postman、SAP、SmartBear、Vonage 等。

展开阅读全文
23 收藏
分享
加载中
最新评论 (2)
3.1的更新,等了有段时间了。去看看
2021-02-20 11:40
0
回复
举报
有了规范,就能很好的指导API设计了
2021-02-20 10:34
0
回复
举报
更多评论
2 评论
23 收藏
分享
返回顶部
顶部