引入Swagger

2019独角兽企业重金招聘Python工程师标准>>>

首先分析下为什么需要使用Swagger，考虑如下一个应用场景

一个新需求被发掘出来，工程师就需要定义好API让页面和服务器能够进行通信

• 不那么聪明的方式是将API的协议写在Doc文档上，通过邮件传给相应的开发人员，这种方式经常因为文档的不一致而导致各种沟通与连接问题

• 稍微聪明的办法是把文件放在公司内部服务器上，这样能稍微减轻上诉问题但是仍然不能够解决文档不一致带来的问题

• 更好一些的办法是采用云笔记或者Google doc等在线文档编辑器或者Wiki里进行编辑和阅读，这样文档几乎大家都保持一致了

• 文档写好后有千奇百怪的形式，有人用txt，有人用doc还有人用xml等等

• 好不容易统一好api的文档格式之后，api的表现力又各不相同，比如有人很简约的写了类说明，没有Schema，没有测试用例等等

• 所以Leader又花精力去确认了API的表现形式，必须写什么，怎么写

• 规范出来了，但是程序员打死都不愿意写文档

• 于是有人就想着搞一个API工具来自动生成API文档，减少程序员写文档的工作

• 程序员把API工具集成到代码中，写了一大堆与业务无关的API文档格式，终于可以输出API文档了，

• 写完API文档，前端和后端工程师就开始投入精力编写交互代码了，实体类，访问方法等等

• 需求发生了一点调整，前端和后端工程师又得重新改下实体类，访问方法之类的巴拉巴拉。

• 项目马上上线了，测试说我要接入进来了，测试也编写了一大堆的访问curl，还得经常找工程师问是不是这样写啊，有没有问题啊等等一堆事

• 终于项目上线了，回头一看，我们发现花了好多时间在沟通上，访问协议的编写上，程序的联调上，真正业务逻辑的分量没多少

上述场景其实可以归纳为 文档表现形式不一阅读困难，自己编写代码导致的大量的沟通与联调工作，这些都极大的降低了程序员的效率及团队的开发速度

那么引入Swagger后能给我们带来怎样的变化？

Swagger约定了一套API的编写格式，可以用于规范我们的API编写质量，按照它的格式写错了会有提示，所以写出来的文档是可以被调试通过的

按照它的格式编写完文件之后，Swagger可以帮我们生成Html文档，将Html部署到网站后，大家看到的文档都是同一份

同时Swagger提供根据Swagger数据文档生成客户端/服务器端/测试端代码的功能，生成代码后大家把代码拿到相应的部署地方不需要任何调试

所以通过Swagger可以极大的降低出错的概览及开发速度

 

如何使用Swagger

我们在swagger.io 网站上编辑swagger.json文件

编辑完文件之后可以将json上传到github

github检测到推送之后hook jenkins工程

jenkins工程集合了swagger的html代码生成器与code generate两个工程

jenkins生成html之后将代码部署到api文档网站

生成客户端代码后提交到相应的Github工程

 

转载于:https://my.oschina.net/guangwei/blog/548394