swagger可能是目前开发resful API时最流行的工具集，可能很多童鞋在遇到API开发需求时，直接反应会是：“用swagger不就好了？”。
protoapi与swagger会有一些理念上根本性差异，为详细阐述这些差异，我们先来看看swagger是如何发展起来的。
文档先行 vs 实现先行
swagger最早是在2011年开源，它处理提供的是：
-
机器可读的
API JSON定义- 它后续又发展成为OpenAPI Specification
- 基于API实现代码来生成
API JSON定义 - 基于
API JSON定义提供web界面，以：- 方便查看API文档
- 快速测试API调用
- 基于
API JSON定义生成客户端SDK
它核心的思路是API实现先行，即，先有服务器端的API的实现代码，然后通过静态分析这些实现代码，去生成机器可读的API JSON定义，以及文档等等。
说白了，我们可以理解为这是服务器端开发人员，习惯于直接实现API，然后又懒得写API文档，在写实现代码的时候，顺手写一下注释，然后使用swagger结合代码 + 注释生成出来文档。
而protoapi强调的则是文档先行，想要实现API的话，必须 先用protobuf作为IDL，把API先给定义好了，IDL即文档，而且是人类可读。
protobuf有严格的语法以及成熟的编译器，当然也是机器可读的。
swagger code-gen
文档先行与实现先行孰优孰劣，这几乎不需要讨论，因为swagger后续也推出了swagger-codegen项目，提倡文档先行，即开发API的时候，先写API JSON定义（我们也可以认为这样的API JSON定义是IDL），然后再使用swagger-codegen去分别生成服务器端已经客户端的SDK。
这样的做法，其实跟protoapi的文档/IDL先行非常类似，区别在于，swagger使用的是类似下面的机器可读JSON格式：
人类去读机器可读的JSON格式，是很容易脑壳疼（前同事的评论）的，因此swagger又提供了Swagger Editor这样的web编辑器。
而protoapi选择的protobuf则是人类可读的格式，各式文本编辑器、IDE均有其插件，可以方便的阅读、编辑：
协作的差异
IDL是否方便阅读、编辑其实还是小问题，重要的其实是对于团队协作的影响。
swagger更多是使用在提供给第三方调用的场景，比方说github。
在这样的场景下，API提供些什么，完全是由服务器端实现者决定，他们在提供API的时候，其实也不会针对特定的业务场景，调用者会如何使用API，只有当调用者开发具体业务的时候才会知晓。
并且，是API开发完毕、发布之后，API调用者的角色才会出现。
问题是，这样的场景往往则跟公司内部项目，特别是走前后端分离架构的项目不符。
但我们日常开发公司内部项目的时候，现实情况很可能是这样：
- web前端、客户端、后端API可能需要同时开发
- 实现的是新业务，业务从项目开始就确定
- 后端提供的是特定业务的API，而不是通用、业务中立的API
- 调用方（web前端、客户端）很可能更了解具体什么API更合适
在这样的场景下，如果我们还是走swagger默认所提倡的实现先行的开发模式，是非常不合适的：
- 调用方需要等待后端API开发完毕之后，才可以了解API
- 两端无法并行开发会严重拖慢项目进度
- 后端闭门造车提供的API未必最适合具体业务的需要
- 调用方难以推动API变更
- 服务器后端，顾名思义是要有服务意识的
而如果采用protoapi这样文档/IDL先行方案，流程很可能是：
- 调用方定义特定业务需要的API，proto文件保存在独立的代码仓库
- 后端、调用同时进行开发
- API需要变更的时候，各方均可以对保存proto文件的代码仓库发起合并请求
这里，重点是将API定义，与API实现、API调用三者解耦剥离开来：
-
API定义先行，定义者可以是API实现方，也可以是调用方，更可以是第三方 - 有各方中立的具体形式方便各方协作推动API的修改
这样的开发方式更加符合敏捷流程。
总结一下
| protoapi | swagger | swagger-codegen | |
|---|---|---|---|
| 开发流程 | 文档先行 | 实现先行 | 文档先行 |
| 开发模式 | 敏捷开发 | 瀑布流 | 偏瀑布流 |
| API定义者 | 前后端均可 | 后端 | 后端 |
| 变更流程友好 | 是 | 否 | 否 |
| IDL | 人类+机器可读 | 偏机器可读 | 偏机器可读 |
| 前端代码生成 | 有 | 有 | 有 |
| 后端代码生成 | 有 | 无 | 有 |
我很久之前就使用过IDL去做各式代码生成，并使用在之前公司几乎所有的项目当中，protoapi与我而言，并不是什么新颖的概念/实现；而是成熟、经历过百项目长期考验的技术思路；相关的技术也都并不高深，属于直接了当，明显没有bug的实现。
我一直没有全面阐述过相关技术背后的理念。这次我重新整理写这系列API的文章，反响最强烈的其实是客户端、前端的多位前同事。
protoapi所提倡的是，是敏捷、流畅互动的团队协作，而不是“我定义、你接受”这样偏单向的流程。
后面我会整理一下protoapi的实战案例，并将项目开源，暂时只是先在github上占个坑，欢迎star：github.com/yoozoo/protoapi
