随着 OpenAPI 规范 3.0 版本即将进入 Beta 候选阶段，这一系列文章旨在从技术开发者社区 (TDC) 的角度提供对变化内容和方式的见解。第一篇文章描述了规范下一步演变背后的背景和基本原理，第二篇文章涵盖了结构性变化，第三篇文章讨论了请求参数。
协议和有效负载
OpenAPI 规范在描述标准请求/响应 HTTP API 方面取得了巨大的成功。但是，社区中的许多人表达了对描述超出简单 HTTP 模型的分布式 API 的兴趣，例如 WebSocket API、RPC API、超媒体 API 和发布/订阅 API。经过 TDC 的多次讨论，目标是将规范扩展到其中一些新的用例，而不会增加现有用例的复杂性。
回调
Webhook 以发布/订阅模式利用 HTTP，并且已成为 API 提供商（包括 Slack、GitHub 和许多其他流行服务）中的一种流行模式。Webhook 使用简单，并且很好地融入现有的基于 HTTP 的 API 样式。但是，对 OpenAPI 规范的一个批评是它无法描述出站 HTTP 请求及其预期响应。新的回调对象使这成为可能。一个回调对象可以附加到订阅操作，以描述订阅者可能期望的出站操作。
链接
已经向 GitHub 上的 OpenAPI 存储库提出了许多描述超媒体 API 的方法。一个主要问题是，超媒体 API 中资源的静态描述与超媒体 API 的运行时/发现哲学优势背道而驰。尽管如此，描述 API 中资源之间静态关系的能力仍然具有一定的好处。为此，3.0 草案规范引入了链接对象以便描述可以根据从初始资源检索到的信息访问哪些新资源。这并非一定是超媒体驱动的，因为新资源的 URL 尚未嵌入到返回的有效负载中，而是根据 OpenAPI 规范中定义的规则构建的。引入了一种新的表达式语法，以允许将响应中的信息与链接操作中的参数相关联。
资源之间链接的静态描述应该允许生成更有用的文档和客户端库，这些库可以封装从一个资源遍历到另一个资源的过程。这可以允许客户端库减少客户端应用程序和服务器定义的资源层次结构之间的耦合。
JSON Schema
人们提出了许多请求，要求扩展 OpenAPI 规范允许的 JSON Schema 子集，以包含 JSON Schema 的更复杂功能。在 2.0 规范过程中，围绕代码生成的潜在工具复杂性促使排除了 anyOf 和 oneOf。但是，许多用户要求放松该约束，即使这会影响对这些功能的工具支持。这是规范设计中的一大挑战，在做出此类选择时，永远无法轻松地知道是提供人们可能伤到自己的锋利工具更好，还是依靠经验说“不”，这种责任的负担太大了。虽然 OpenAPI 2.0 采用了更保守的方法，但用户群已经变得更有经验，因此一些限制正在解除，用户将不得不做出明智的选择。
替代方案
随着对非 JSON 媒体类型支持的改进，仅使用 JSON Schema 来描述有效负载的限制变得越来越难以维持。TDC 目前正在探索如何启用描述非 JSON 有效负载架构的选项。如果能够克服这一挑战，则可能可以完全删除表单参数类型，并启用对使用 protobuf 和 protobuf 架构的 gRPC 等协议的支持。
下一篇文章将讨论一些计划对文档进行的改进。
关于作者