转载

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

本系列文章专注于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的生物信息小组领导软件开发工作，这是一个基于硅谷的新药研发公司。