THE WORLD'S MOST POPULAR API TOOLING
swagger的简介和使用方法不是本文重点，网上有很多介绍的文章。
swagger官网:http://www.swagger.io
-
项目开发中的沟通问题
现在的软件开发项目中，客户端与后端开发人员之间因为API变更而引起的不必要的互撕行为时有发生，这肯定会影响项目的执行速度。
-
我们的目标是“没有沟通”：Talk is cheap, show me the code！
在需求确定以后，一个统一规范，语义丰富的Spec既可以提供一个统一的API标准， 而且对应的在线文档能够使得API变化可以及时通知到团队中的相关人员。要保证以上需求可以完美实现就必须要排除软件开发中最大的不确定因素：
人。工具化就是不二之选。
-
为什么要选择Swagger：
Swagger基于OpenAPI Specification（OAS），作为一个功能强大，语义丰富的协议，贯穿整个API的生命周期，从设计到文档，从测试到开发，对于基于RESTful API的全端开发可以天然作为一份合约（Contract），成为开发组内前后端间沟通的桥梁，使得开发团队可以基于Swagger描述的框架针对各自的开发环境进行项目的构建。Swagger框架自带的文档工具也解决了设计人员编写API文档以及团队间共享API文档的难题。
使用基于swagger的全端工作流程会显著提高团队的工作效率
基于swagger的全端工作流程如下：
利用Gitlab Web Hooks的特性，在维护yml的项目的web hook中添加codegen的trigger。codegen拉取更新后的yml，根据各个子项目的配置生成各端代码并push到相应的分支中。开发人员切换到对应的分支后即可无需考虑API部分的实现， 立即根据swagger文档开始开发。
移动端情况:
-
Android端将Swagger协议解析为基于Retrofit2+RxJava的网络模块实现，IOS端则解析为RxSwift+Alamofire。
移动端根据json文件自动生成整个网络模块的代码。这样移动端网络层的开发和维护工作就直线下降为接近于0，开发人员只需专注于业务功能的实现。而且职能内部也基本杜绝了因为API问题产生的沟通成本。
Web 端的情况：
-
浏览器端使用ajax访问后端接口，Swagger作为接口文档，节省了绝大部分的 沟通时间
-
Node.js端生成完整的接口模块，在接口有变更时，只需重新生成模块即可，对业务代码几乎不会产生影响。
后端的情况：
在应用了基于Swagger的全端工作流程后，除了便于前/后端，移动端/后端沟通 接口外，对于后端而言，还提供了如下的便利：
-
框架代码与API Handler生成
之前，对于定义好的接口，需要工程师手工编写程序框架和API Hndler代码。对于相对大型的项目而言，这部分的工作不仅繁杂，而且极易出错。采用了S wagger生成框架后，这部分代码可以即时完成，大大提高了开发效率，同时也避免了人工输入容易出错的问题。
-
参数与返回值校验
RESTful接口的参数，有哪些基础类型，定义成哪种结构，如果没有一个统一的第三方定义，极易造成混淆，可能会导致难以发现的bug，比如不同字节的int。另外，参数的有效性校验也是一个繁重的工作，每次手写参数校验也极易出错。采用swagger生成框架后，不仅代码容易生成，更重要的是，参数类型和结构也有了统一的标准（OpenAPI Spec），避免了开发中潜在的种种问题，提升了开发与 沟通的效率。
-
token鉴权
对于生产环境而言，API的token鉴权是必不可少的。这部分功能相对内聚，通过Swagger生成的框架，可以集中生成这部分逻辑，对于开发人员而言，鉴权模块完全是透明的。这样不仅提高开发效率，而且对于后续token鉴权的维护和升级也可以很容易的进行，甚至完全不需要业务逻辑代码的调整就可以完成。
整个流程下来各个职能部门只要专心做好本只能内部的事情就可以了，而且本职能内底层代码已经自动生成，显著地降低了开发成本。
