ThinkSSL🔒 一键申购 5分钟快速签发 30天无理由退款 购买更放心 广告
[TOC] # 简介 现在的网站架构基本都由原来的后端渲染,变成了:前端渲染、先后端分离的形态,而且前端技术和后端技术在各自的道路上越走越远。 前端和后端的唯一联系,变成了API接口;API文档变成了前后端开发人员联系的纽带,变得越来越重要,swagger 就是一款让你更好的书写API文档的框架。 # 其他API文档工具 类似的API文档工具网上还有很多,但是能拿上台面的,不多。RAP是由阿里开发的,整个阿里都在用,还不错。github地址为:https://github.com/thx/RAP 当然咯,rap 不可能只有线上版本,肯定可以[部署到私服](https://github.com/thx/RAP/wiki/deploy_manual_cn)上。 # [Swagger](https://github.com/swagger-api) 方便的管理项目中API接口,目前最流行的莫过于Swagger了,功能强大,UI界面漂亮,并且支持在线测试等等。 Swagger 是为了描述一套标准的而且是和语言无关的 REST API 的规范。对于外部调用者来说,只需通过Swagger文档即可清楚Server端提供的服务,而不需去阅读源码或接口文档说明。 中文网站:http://www.sosoapi.com ## 三大功能 1、**[Swagger Editor](http://editor.swagger.io/)**: Swagger提供的一个编辑器,用来通过Swagger提供的特定的YAML语法来编写API文档。 2、**Swagger Codegen**: 代码生成器 3、**[Swagger UI](http://petstore.swagger.io)**: YAML语法定义我们的RESTful API,然后它会自动生成一篇排版优美的API文档,并且提供实时预览。 # 产生的背景 **前后端分离** 1、前后端仅仅通过异步接口(AJAX/JSON)来编程 2、前后端都各自有自己的开发流程,构建工具,测试集合 3、关注点分离,前后端变得相对独立并松耦合 ## 面临问题 1、没有统一的文档编写规范,导致文档越来越乱,无法维护和阅读。 2、开发中的接口增删改等变动,需要较大的沟通成本。 3、对于一个新需求,前端开发的接口调用和自测依赖后台开发完毕。 4、将接口的风险后置,耽误项目时间。 ## 解决方法 1、接口文档服务器 -- 解决接口文档编辑和维护的问题。 2、mock 数据 -- 解决前端开发依赖真实后台接口的问题。 ## 接口文档服务器 后台通过引入 Swagger 的相关依赖包和配置。 后端 Java 代码通过配置 Swagger 相关注解,可以更好地解释 API 。 最后,为前端提供 Swagger-UI 地址,启动服务后,访问:http://localhost:8080/swagger-ui.html 就完成了集成。 # [SosoApi](https://github.com/sosoapi) 是一个专注于API接口文档管理及线上线下测试的API服务平台。 ## 特点  提供丰富的在线文档,包括线上编辑和线下部署及常见问题,减少上手学习成本。  通过编辑表单的方式创建基于swagger ui的数据文档,从而可在线预览和测试。  解决了swagger editor学习成本高及代码集成不好维护的问题。  为方便小团队及公司内部使用,可导出swagger数据文档线下部署。  不会对已有项目产生任何代码入侵。 ## 使用 登录[官网](http://www.sosoapi.com/)使用,上面有详细的指导手册,大家一看就明白了。这里主要补充一点:sosoapi 去年还没有添加“导入”的功能,今年增加了,但只有在线的版本有导入功能,开源版本没有,所以笔者推荐使用在线版本以节省人力。有了导入功能,那么只要导入接口的 json 文件就可以自动生成接口文档了(刚好 swagger 可以生成 json 文件),我们只要输入必要的参数就可以进行测试了。 ## 配合 同时使用 Swagger 和 [SosoApi](http://www.sosoapi.com/),使用Swagger生成 json 文件,然后将 json 文件导入 sosoapi,就可以得到接口文档及可导出多种格式的接口文档。 # 契约测试 谈到了前后端分离,那么在所难免,会遇到一些集成的问题:一拨人在全心全意的进行前端开发,另一拨人在心无旁骛的做后端开发,那么谁应该为集成买单呢?在现在这个持续集成、持续交付的年代里,我们应该如何去保证双方不会分道扬镳、越走越远呢? 所以,在一开始就定一个契约就成了迫在眉睫的事情,双方就API相关的内容,包括路径、参数、类型等达成一致,当然,这份契约并不是一旦创建就不能修改的,而且,如果一开始没有设计好,很有可能会频繁的修改。这个时候,要让双方都能够实时的跟踪最新的API就成了一个难题。还好,在总结了前人的经验和教训之后,我们早已有了应对之策,那就是契约测试。 首先,我们先假设我们已经有了一份契约,可能是基于JSON格式的,有可能是基于XML格式的,这都不重要。然后,前端会根据这份契约建立一个Mock server,所有的测试都发往这个Mock server。有两方面的原因:一是这个时候可能后台的API还没有开发完成;二是有可能因为网络等其他方面的原因导致直接调用真实的后台API会很不稳定或者很耗时。到这里,可能有人就要说了,如果后台的API实现和之前约定的并不一样,怎么能保证到了集成的时候双方还能很顺利的集成呢?其实这个问题并不难,只需要让前端的测试定期连接真实的API执行一遍就能尽早的发现差异性。比方说,在我们平常的build pipeline上添加一个job,让这些测试每天在午夜里连着真实的API执行。如果,第二天发现这些测试有的失败了,那么就需要和开发后台API的人员进行一次沟通了,很有可能由于真实的业务逻辑发生了变化,API在实现的时候,已经和之前的契约不一致了,如果是这样,那么相应的测试和契约定义就需要更新以满足最新的业务需求。 总之,进行契约测试的目的就是尽早的发现差异性,并作出调整,将最后集成的风险降到最低。 # 参考 [http://apijson.org/](http://apijson.org/) # [RESTful API 设计指南](http://www.ruanyifeng.com/blog/2014/05/restful_api.html)