技术只有在创新要素的支持下才能普及。以 iPad 为例，虽然平板电脑的概念在 iPad 于 2010 年发布之前就已存在多年，但苹果公司之所以能凭借 iPad 取得成功，部分原因在于当时 Wi-Fi 连接的普及。

如果连接的普及使平板电脑成为现实，那么描述格式的普及则使 API 获得了商业成功。OpenAPI 规范 (OAS) 已成为世界范围内 restful 接口的标准描述格式。OpenAPI 规范是您 REST API 的人类友好、机器可读的接口。OpenAPI 规范描述了 API 的功能，包括 API 公开的资源以及它们对应的请求和响应。

该格式促进了 API 内部利益相关者与其外部消费者之间的可访问性和协作。简而言之，OpenAPI 规范改变了 API 的构建和交付方式。

OAS 由 Linux 基金会旗下的 OpenAPI 倡议 (OAI) 管理。作为 Linux 基金会下的一个开放治理结构，OAI 致力于创建、发展和推广一种供应商中立的描述格式。

在今年的 API 策略与实践大会 (APIStrat 2017) 上，我有幸与 OAI 技术指导委员会 (TSC) 成员 Darrel Miller 进行了交谈。Darrel 分享了关于 OAS 项目当前状态以及业界如何采纳最新版本规范 OAS 3.0 的宝贵见解。

OAS 3.0 的当前状态

OAS 3.0 于今年早些时候发布？到目前为止，您收到的反馈如何？

到目前为止，反馈非常积极！我们对结构进行了一些很好的清理和重组，使规范更具可读性。令人欣慰的是，我们在 OAS 3.0 中所做的一些更改使我们与 HTTP 的工作方式更加一致，并使许多开发人员能够充分发挥其功能。

我们确实看到许多人对 WebHooks 和链接功能感到兴奋。链接功能是一个非常有趣的“通配符”。我认为利用它有可能做很多很酷的事情。许多人错误地认为我们试图体现超媒体，而围绕链接与人们进行对话总是很有趣的，尤其是考虑到我自己在超媒体方面的背景。

OpenAPI 规范 3.0 正在解决那些喜欢使用静态设计原则构建 API 并定义其 API 中操作和资源之间关系的公司的一个实际需求。它无疑已成为关键的基础设施组成部分。

我认为 OAS 3.0 也有可能极大地改进 API 文档，因为突然之间，您现在可以描述通过 API 的流程。我认为场景是描述和文档化 API 的更好方式，而链接有助于我们实现流程之间文档自动化的目标。我很乐意看到人们围绕此构建一些工具。

我个人希望看到更丰富的 API 文档用例和资源之间更好的关系处理。

我的意思是，当你面对一个 API 时，你会问：我如何使用它？我从哪里开始？有 150 个资源和一个很长的字母列表，你必须开始查看路径结构，并决定这意味着什么，然后尝试从中推断。然而，如果你能实际告诉你的消费者：“看，这是你的起点，从这里你可以去请求信息。”

你不需要遵循那个路径。你可以跳到那些端点，但至少对于理解 API 是如何构建的来说，这显著增加了 API 结构中的语义。

采纳是任何技术事业的巨大组成部分。OAI 如何教育和推广 OAS 3.0？

我认为在工具支持尚不成熟的时候，不宜过早进行大规模推广，但到目前为止，看到它的普及情况令人欣慰。我们意识到 OAS 获得大规模采用的唯一途径是提供更多的工具支持。我们在 GitHub 项目上有一个实现页面，列出了所有支持 OAS 3.0 的工具。看到这个列表每天都在增长，这非常令人兴奋。

在围绕 OAS 的工具方面，我们看到其在不同技术之间有着良好的传播；从 Ruby 和 NodeJS 到 .NET 和 JavaScript。

为了进一步支持我们的市场营销计划，我们已与一家营销和品牌公司签约，以提高对 OAS 的认知度。我们也考虑过倡导，但我认为现在还为时过早，因为我们仍在确保获得所有正确的工具来支持 OAS 提供的所有功能。

APIStrat 2017 是 OAI 赞助的第一个大型活动。您在今年的会议中注意到了什么？

今年的 APIStrat 显然更加强调 OpenAPI。我希望这更多是因为在过去的 12 个月里，我们发布了新版本的规范，并且在 API 领域，人们终于就 OpenAPI 作为 REST 接口的标准描述格式达成了共识。我认为我们都知道拥有 API 描述的价值，最终我们可以停止争论哪种格式最好。我们可以真正开始将越来越多的工具引入到围绕它的生态系统中。

规范和工具的演变

随着不同的组织对 OAI 投入如此之多，这如何促进了规范的演变过程？

这根本没有发生显著变化。OAI 的架构旨在确保社区中每个人的声音都能被听到。当成员公司加入该组织时，他们基本上是在公开声明他们支持 OAS，而不是影响其演变。OAI 的成员资格与规范构建本身的技术方面完全独立。

社区中任何对 API 感兴趣的人都可以尽其所能地做出贡献。您无需成为会员即可为规范做出贡献，就像您无需成为会员即可阅读、使用和受益于该规范一样。

拥有行业公司加入 OAI 对于保持势头、在该领域获得知名度以及建立 OAS 的信誉非常有益。然而，从技术角度来看，它没有任何直接关联。从技术前景来看，重要的是让更多人加入。我们将专注于争取让更多核心人员进入指导委员会。已经有许多人对该项目做出了广泛贡献，我们希望提名并邀请这些人加入指导委员会。这将使他们对规范中包含的具体内容有更多的发言权，并帮助我们联系更多的社区成员以获取更多输入。

为了让更多人贡献，我们在完成 OAS 3.0 后花了一些时间进行内部整理，并整理了我们的治理事务。我们正在制定开发者指南，以向希望贡献的人明确我们推荐的流程类型。

规范的原始版本，即 Swagger 规范，由于其众多现有工具而广受欢迎。展望未来，OAI 是否有计划与更多供应商合作？

我们一直在尽力鼓励更多人构建工具，OAI 的一些成员也正在构建工具。我们对 OAI 的角色和职责与工具之间进行了相当严格的区分。我们只负责规范的治理。我们不希望官方组织拥有自己的工具。所有的工具都是第三方工具；我们只负责创建规范。

到目前为止，我们不需要说服人们构建工具，因为公司们会自发地开发工具。其中很多只是对生态系统中现有工具的更新。这只是一个我们需要完成规范，并且人们需要时间来吸收它并能够展示升级到 3.0 的价值的问题。

在您网站上发布的博客文章中，您提到您最初对 OAS 持怀疑态度。您曾想过自己最终会从事与 OAS 相关的工作吗？

不，我从未想过自己会加入 OAI。我在小组讨论中也说过，这与从技术角度看架构模式的正确性无关，而是它对实际人员工作流程的影响。从我的博客文章中，您会看到我过去是，现在仍然是超媒体的倡导者。

当您使用 OAS 静态设计 API 时，您可以获得某些好处——例如能够生成文档脚手架和生成客户端——但会失去一定的灵活性，这迫使您采用版本控制策略以随时间演进。

这是静态设计和动态设计之间的权衡，我想在某个时候我意识到，我宁愿成为解决方案的一部分，帮助绝大多数开发人员构建更好的 API，即使他们选择的是版本控制路径而非演进性路径。

绝大多数公司正在采取更简单的方法，并利用静态 API 描述的优势。我很高兴能参与到这项倡议中，许多公司都从中获得了巨大的价值。如果我能为 OpenAPI 规范的未来提供指导，以避免某些陷阱，那么我很高兴能成为其中的一部分。

您认为 OpenAPI 会不会发展到支持其他框架或架构，比如 GraphQL？

HTTP 的设计具有扩展点，其中一种体现方式就是媒体类型。Webhooks 非常棒，因为 Webhooks 自然地融入了 HTTP 模型。

GraphQL 定义了一系列可以非常自然地成为媒体类型的事物。查询的媒体类型、结构化响应的媒体类型等，它们都有自己的类型系统。如果现有类型系统不能满足您的需求，这很酷。 Web 之所以取得巨大成功，是因为它在请求、您在层次结构中描述的资源以及您可以完全独立地发送回的有效负载之间，实现了非常好的关注点分离。

回到 OAS 的能力，如果任何架构风格是为了很好地融入 HTTP 而不是试图在 HTTP 之上分层构建的，那么它就适合 OAS。我喜欢创新，喜欢人们创造新事物。GraphQL 本可以很好地融入其中，并与我们所有现有技术并存。我真正希望他们做的是以一种更自然地适应 HTTP 生态系统的方式来构建它。

我能看到的唯一另一种适合 OAS 的主要风格是 RPC 类型的 API，在这种 API 中，您实际上是将操作作为请求正文的一部分进行隧道传输。这对我们来说仍然是一个挑战，因为我们使用路径来标识操作。我一直在脑海中反复辩论我们应该如何让操作通过路径之外的方式来标识。例如，在 OAS 3.0 中，我们有这个新的运行时表达式，可以加以利用。现在，我不确定这是否会奏效，因为那样您就会有一大堆操作都使用相同的运行时表达式。它们可能有不同的操作 ID 来唯一标识这些操作，也许？但问题是，到那时我们是否离 HTTP 的工作方式太远了？

在这一点上，有一些非常有趣的讨论，尤其是在如何扩展我们所能支持的范围，同时又不会开始用并非每个人都觉得有价值的东西污染规范。如果你开始做那种邻近的 RPC 相关的事情，会感觉有点不妥，尽管我很乐意找到一种方法来支持那些希望以多种方式设计 API 的人。

所以您刚才告诉我们，OAS 想要支持的任何新功能都需要符合 HTTP 的工作方式。这些功能的可用性也是一个考虑因素吗？

我的意思是，这对于普及至关重要，对吗？我将此归功于 Tony Tam（原始 Swagger 规范的创建者），他将很多这方面的理念融入了规范。他总是会反对任何过度工程化或对最终用户来说过于复杂的东西。

我们现在正让那些并非全职开发人员的人开始设计和构建 API，因此拥有一个易于使用的描述格式变得至关重要。我实际上在 OpenAPI 聚会上与一些业务分析师和产品经理（而不是经验丰富的开发人员）进行过交流。他们可能对如何实现 API 没有最好的想法，但他们理解 API 应该涵盖的业务场景。

结束语

我想通过了解在 API 领域中，最令您兴奋的未来发展方向来结束这次对话？

我想看看人们如何利用 OAS 3.0 的链接和文档。API 文档可能会变得异常困难，几乎达到令人痛苦的程度。我希望有比我拥有更多技术写作技能和更优秀 UI 知识的人，能够利用我们用 OAS 构建的东西，加以发展，并创建基于场景的文档脚手架生成器。

生成的文档能提供的帮助有限，但基于场景的脚手架可以消除生成大量可消费信息的单调性。我认为这是最令我感兴趣的事情之一。

然后我们就可以在此基础上添加额外的价值。这绝对是一个有趣的领域，我对未来充满期待。

有兴趣开始使用 OpenAPI 3.0 吗？查看我们的免费培训： OpenAPI 3.0 及其对 Swagger 未来的意义