通过Swagger进行API设计，与Tony Tam的一次对话-InfoQ

本系列文章专注于 Web API__ 之 “元语言”的三个关键领域：即 API__ 描述、API__ 发现以及 API__ 档案。这些文章将涵盖所有这三个重要的趋势，并包括对这一快速发展的领域的一些关键人物的专访。

来自 InfoQ__ 的这篇文章是“描述、发现以及档案：进入Web API__ 的下一阶段”系列文章中的一篇，你可以在这里进行订阅，以便通过RSS__ 获取新文章的通知。

要找到 Tony Tam 真不是一件容易的事，他总是日理万机难以抽身。人们对于 Tam 的了解多数来自于在他的影响下出现的 Swagger ，这是目前最流行的一种 Web API 规范框架。Tam 同时也是 Reverb 的创始人，这是一家进行内容分析与推荐业务的公司。他还是 Wordnik 的奠基人之一，这是世界上最大的在线英文辞典。自从他在加州大学圣塔芭芭拉分校与圣塔克拉拉大学就读以来，他已经参与了数家公司的创立。他甚至还拥有一项基于内容获取创建用户档案技术的专利技术。如今Reverb 已经被NDN（ newsinc.com ）所收购，而 Tam 正在新兴技术部副总裁这个新职位上忙得不亦乐乎。

这段时间对于 Swagger 框架来说也是一个繁忙的季节，在 Swagger 的开放工作小组（自2014 年5 月成立）的不懈努力下，Swagger 2.0 终于在2014 年9 月正式发布了。我们的采访是在2015 年3 月进行的，此时距2.0 的工作启动还不足一年。此外，不久之前Reverb 刚刚宣布Swagger 规范未来的发展将转交给 SmartBear ，这是一家位于马萨诸塞州的软件工具公司。

人们对于近期的一些事件还记忆犹新，因此我们的对话将从 2009 年 Swagger 框架启动时说起。

Mike Amundsen**：Swagger API框架原本并不是一个公开的项目，而是在 Reverb（当时还称为 Wordnik**）内部开发的一个项目，这可能会让人们感到吃惊。你能为我们介绍一下 Swagger项目刚刚成立时的一些情况吗？

Tony Tam：启动 Swagger 这个项目的目的是克服当时在 Wordnik 的工作中所遇到的一些真实的挑战。当时我们正在创建 REST API，由我们的付费客户进行调用。在公司内部，我们为系统打造了一个统一的 API 接口，希望根据我们与每个客户之间的协定为他们开放权限。也就是说在文档中只记录他们有权限使用的操作。此外，客户还要求我们向其提供原生的 SDK。

Mike：因此为了解决创建大量的自定义接口与文档的麻烦，你们就设计了 Swagger是吗？

Tony：是的，而且我也很讨厌重复地做一些完全相同的事。我们当时想到了一个点子，就是为我们的 REST API 创建一个泛用的 JSON 模型，它能够反映出调用者有权限进行哪些操作。它成为了我们的代码生成器的输入模型。之后，在我们办公室中有一位非常聪明的开发者指出，我们应当如何使用这一模型以打造一个交互式文档的 UI，它后来就成为了 Wordnik 开发者网站。正是通过 JSON 模型与交互式文档的概念相结合，才有了我们如今称为 Swagger 这一框架的出现。

Mike：那么，Swagger又是怎样一步一步成为如今被广泛使用的一个面向公众的工具呢？

Tony：在我们将交互式 UI 发布至 http://developer.wordnik.com 之后，我们对于这一项目的兴趣也是水涨船高，并最终将它的 UI、服务端集成以及代码生成部分全部进行了开源。

这个项目的初始目标是处理一些现实世界中遇到的挑战，虽说它目前的发展已经远远超越了它起初的模样，但核心的思想依然是为 API 定义一个一致的、可预测的模型。

Mike**：你从 2009年开始从事 Swagger的开发，而 Swagger 2.0版本刚刚在 2014年秋季发布。发布新版本的主要动力是什么，Swagger在新版本中又迎来了哪些变化呢？**

Tony：经过了多年的参与之后，你肯定已经清楚哪些方式行得通、哪些行不通。在之前版本中有一些结构化方面的问题，它会造成大量的支持问题，此外我们也希望在 Swagger 规范中对 JSON 格式的 schema 进行更好的支持。我们还希望让定义变得更简洁，并且便于在建模工具中进行编辑。

Mike**：那么，对于 Swagger用户来说，“2.0”是一个破坏性的版本吗？**

Tony：我们在过去三年间发布了 Swagger 的 1.0、1.1 与 1.2 版本，它们与原始的设计相比只有一些小幅度的改进。而这一次，我们借此机会对 Swagger 规范进行了一次较大的改动。

当然，我们在每个版本中都尽量做到让升级工作变得更简单。即使 Swagger 2.0 中有如此多的变化，但服务端工具、UI 与代码生成模板依然具有良好的兼容性。一般情况下只需对依赖进行相应的升级就可以了。

Mike**：Swagger 2.0中的一个新特性是允许定义扩展。为什么要加入这一特性？是否能够举例说明一下 API开发者应当如何使用这些扩展？**

Tony：这个特性推动的动力来自于以下几点。

首先，我们并不想把所有可能的特性都塞到这个规范中去。先前曾有人建议将调用频度限制的功能也加到规范中，但这一特性很难实现泛用性，由于大多数用户都不会在意这一特性，因此我们不想因为它而污染了这一规范。

其次，我们从 Swagger 的最初几个版本中学到了一个经验：如果没有一种简单而健壮的校验机制，那么很容易就会写出无效的规范。我们最终选择了 JSON Schema 校验工具，并将这一工具直接加入 Swagger-UI 项目中。这是我们的工具集中非常重要的一部分，它能够帮助开发者编写有效的 Swagger 定义。

要从规范中移除结构化的限制，同时要保留一种健壮的校验工具，实现这一点非常困难。我们所选择的方式是在规范中通过使用一种扩展前缀获得更大的灵活性，开发者能够让 Swagger 产生更大的实用性。有些非常实用的扩展有可能会在下个版本的 Swagger 中“升级”为标准特性。

Mike**：Swagger 2.0的发布似乎得到了来自社区的极大影响，包括大量的变更请求与新特性。你如何决定在 2.0中加入哪些变更呢？**

Tony：Swagger 2.0 规范中包含了所有我们认为有意义的特性，这个项目不是由时间线或某个特性集所驱动的。我们获取了大量有价值的建议并认真聆听。最终，我们基于规范的核心目标做出决策，而不是尝试同时解决所有人的问题，后者只会使你的项目变成一个大泥巴球。

Mike**：有一个特性请求最终没有出现在 2.0版本中，即对于超媒体描述的支持。但在 Github上，这一 **问题处于已关闭状态，并描述为“不在设计考虑中”。超媒体在 API设计的地位正在不断提高，为什么你认为它不应出现在 2.0版本中呢？你认为它有可能会出现在今后的版本中吗？

Tony：这个提交信息本身已经说得很清楚了，Swagger 的这个版本并非是为了超媒体而存在的，或许它在某种程度上确实有存在的意义，但即使加入对 Hypermedia 的支持，也无法实现 Swagger 目前的任何目标。或许它们之间确实有些格格不入，但我对此也不是非常确定。

Mike**：虽然 Swagger出现至今还不到 5年时间，但它在 Web API的开发者中已经有了大量的粉丝。它的足迹似乎比其它的一些 API设计更为深刻，包括 WSDL**、WADL**、AtomSvc以及其它。你认为产生这一情况的原因是什么？是什么原因让 Swagger得到了如此 **广泛的应用。

Tony：在我看来，Swagger 能够得到这样的成功，其背后有一些关键的因素。首先，它确实解决了一些常见的问题。你是否能够以一种简便的方式为老板展示你的 API？你怎样让客户试用它？Swagger UI 能够帮助描述这个 API 的功能，以及它的运作方式。

其次，Swagger 规范本身足够简单，开发者在每一种主流的编程语言中都编写过对它的集成。像 Swagger Inc. 这样的企业能够负责整个 API 的工具链，而使用我们的工具的开发者已经不下一万，他们编写了各种不同的集成方式。能够跨语言以及跨框架对 Swagger 的发展非常重要。

最后一点，Swagger 的成长经历与众不同，它不是通过市场宣传，或是在某个充斥着 flash 的网站上展示各种 logo 而兴起的。它的流行完全来自于开发者这一草根阶层自发的支持。

Mike**：在撰写本文时，目前最常用的三个 API描述框架应当要属 Swagger、RAML和 Apiary Blueprint了。你认为 Swagger**与其它两种格式相比有什么优势？开发者会基于哪些因素而选择其中一种格式？

Tony：我在这里可以提几点。这些规范的功能有着明显的不同之处，想要同时支持这三种规范而又不失通用性是不太可能的，因为你无法将某种规范简单地转换成另一种。这就像要你设计一种适合任意尺寸的汽车防尘罩，能够同时适合你的保时捷与房车一样不现实。

Swagger 在所有这些描述格式中的结构是最多的，它的核心目标是能够为强类型语言实现操作与模型的描述，这也意味着我们能够在 API 中提供足够的元数据信息，以生成原生的 C++ 客户端。

Mike**：那么，Swagger是不是一种“严格”的格式，让开发者能够通过它学到创建 API的“正确方式”呢？**

Tony：Swagger 并没有让开发者强制使用一种单一的工作流，它并不强制你选择自顶向下或是自底向上式的编码风格。对于其它格式来说，这确实是一个不可避免的抉择，因为它们对于工作流有严格的规定。

我想大多数开发者在选择描述格式时都会考虑到他们所使用的编程语言。如果某种格式没有符合你的编程语言的实现，你很可能会另请高明。

Mike：有一句话你经常挂在嘴边，在创建 Swagger时，你希望能够避免“CORBA问题”。CORBA问题指的是什么？你在创建 Swagger时又是怎样避免这一问题的呢？

Tony：在我看来，CORBA 问题就是指“为所有人设计”。如果你希望通过某个规范解决每个人的问题，那你肯定无法得到一个成功的规范。这就像设计界中的人所说的一样，“如果你将所有美丽的颜色混合在一起，只会得到一个肮脏的颜色”。这一点对于软件设计来说也一样，当你在设计例如 Swagger 这样的产品时，对于它的功能，必须以一种干净的、清晰的方式进行设计。当设计走上正轨时，就有许多的改进空间，但一切前提在于要把握好方向。

Mike**：SmartBear在 Swagger的发展中扮演了怎样的角色，为什么他们会在这个节骨眼上 **选择带领 Swagger**** 今后的发展？

Tony：SmartBear 是最早一批将 Swagger 整合到他们的工具中的软件商之一。我们已经合作了很长一段时间，在 API 这一领域中，他们最适合领导 Swagger 的发展。他们将通过正确的途径打造开放的规范、工具以及社区。他们很清楚地看到，即使对于以 Swagger 为基础打造的商业产品来说，整个业界也能够得益于一个一致的 API 模型。SmartBear 在 API 测试领域已经浸淫多年，他们在 API 设计方面的声望很可能已超越了其它的公司。

Mike**：如今 SmartBear即将接管 Swagger的发展，那么你在这一规范的未来发展中又将扮演什么样的角色？**

Tony：我当然也在计划继续为这一项目做出自己的贡献。对于需要这一规范的人来说，我们将推出更多的资源与更好的支持，我也将继续工具链与规范方面的工作。

Mike**：Leonard Richardson将标准的发展描述为 **一种连续的发展 **，从法令到个人、从个人到企业、再从企业到开放。第一阶段的法令就是得到共识的行为，而最后阶段则是标准委员会的工作成果，例如 W3C、IETF****、OASIS等等。按照 Leonard的评估来看，Swagger创立时还是一种应用于你的公司的个人标准，然后很快成为了一个企业标准，得到了大量的组织的使用。在你看来，Swagger能否在短期内成为一个开放标准呢？**

Tony：我们正在为 Swagger 规范创建正确的治理结构，这个过程将是公开的，问题只在于这个结构需要有多正式。我预计当分析过程结束后，就应当能够得到正确的结论了。

Mike：还有没有什么我还没有问及的问题，是你打算与读者分享的？

Tony：我想你的问题已经基本涵盖了所有的部分，感谢你的宝贵时间。

关于受访者

Tony Tam是 NDN 的新兴技术部门的副总裁，同时也是工程部门的执行副总裁，负责协助全公司的技术问题。在加入 NDN 之前，Tony 曾是 Reverb 的创始人与 CEO，他在当时领导着网站的创新词汇导航系统的开发工作。他是 MongoDB Masters 小组成员之一，并且领导着 Swagger API 框架的开源工作。在加入 Reverb 之前，他曾是 Think Passenger 的创始人，兼任工程部门的高级副总裁，这是一家设计客户协作软件的供应商。在那之前，他曾在 Composite Software 担任工程师主管，帮助公司开发了第一代与第二代查询处理引擎，并领导着具有专利权的，基于成本的联合查询优化器这一产品的研究与实现。他也曾在 Galileo Labs 的生物信息小组领导软件开发工作，这是一个基于硅谷的新药研发公司。