[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)