swagger，一个全新的维护 API 文档的方式

背景：

随着前后端分离的开发模式越来越流行，前端与后端分别交给不同的人员开发，能很大程度的提高开发效率，但是项目开发中的沟通成本也随之升高，这部分沟通成本主要在于前端开发人员与后端开发人员对API接口的沟通。

在我这几年的开发经历中，最早和前端沟通API接口是通过word文档来完成的，这种方式及其低效，由于API接口不可能一开始就能设计得很完善，每次改动都要重新通知并发送word文档给相关关系人，及其麻烦。其次，也没法提供mock数据给到前端。

后面我接触到别的新项目，API接口沟通使用了rap2，rap2是阿里妈妈前端团队开发的API管理平台，能给我们提供方便的接口文档管理、Mock、导出等功能，极大方便了API接口的沟通，同时，其提供的mock功能，能让前端直接调用得到mock数据，从而避免了前端需要自己造数据的问题，提高了前端的开发效率。这个工具我认为其唯一的缺点就是文档和代码是分开维护的，当后端需要开发接口时，每次先在rap2上定义好，再编写代码，同时要保持二者的一致性，接口少还好，接口多的话这个过程及其繁琐，我是深有体会。其次，在后期版本快速迭代的过程中，修改接口实现的时候都必须同步修改rap2接口文档，而文档与代码又处于两个不同的媒介，除非有严格的管理机制，不然很容易导致写出的代码与接口文档不一致现象。

最后，为了避免上述问题，我们开始采用一个新的API管理工具，那就是swagger，swagger 给我们提供了一个全新的维护 API 文档的方式

Swagger2综述

Swagger是一款Restful 接口的文档在线自动生成、功能测试框架。一个规范和完整的框架，用于生成、描述、调用和可视化Restful 风格的Web服务，加上Swagger-UI，可以有很好的呈现。

Swagger是一组开源项目，其中主要项目如下：

Swagger-tools: 提供各种与Swagger进行集成和交互的工具。例如模式检验、Swagger 1.2文档转换成Swagger 2.0文档等功能。

Swagger-core: 用于Java/Scala的的Swagger实现。与JAX-RS(Jersey、Resteasy、CXF...)、Servlets和Play框架进行集成。

Swagger-js: 用于JavaScript的Swagger实现。

Swagger-node-express: Swagger模块，用于node.js的Express web应用框架。

Swagger-UI：一个无依赖的HTML、JS和CSS集合，可以为Swagger兼容API动态生成优雅文档。

Swagger-codegen：一个模板驱动引擎，通过分析用户Swagger资源声明以各种语言生成客户端代码。

Swagger-UI是什么？

Swagger-UI 是一款Restful接口的文档在线自动生成+功能测试功能软件。

Swagger-UI 的官方地址：http://swagger.io/

官方提供的demo地址：http://petstore.swagger.io/

为什么API接口文档用Swagger-UI？

现在多数的项目开发中，网站和移动端都需要进行数据交互和对接，这少不了使用Restful编写API接口这种场景。 特别是不同开发&测试团队协作时，就更需要以规范和文档作为标准和协作基础。良好的文档可以减少沟通成本，达到事半功倍的效果。 有时对一些API说明的理解比较模糊，总想着能直接验证一下自己的理解就好了，而不是需要去项目写测试代码来验证自己的想法。即API文档应具备直接执行能力，这种能力类似word,wiki等是无法提供。

Swagger-UI 就是这样一种利器，基于Html+Javascript实现，倾向于在线文档和测试，使用和集成十分简单，能容易地生成不同模块下的API列表， 每个API接口描述和参数、请求方法都能定制并直接测试得到直观的响应数据。

Swagger-UI怎么用？

目前官方提供的Swagger-UI 的使用方式主要有2种：

与不同的服务端代码集成，在服务端代码中嵌入SwaggerUI文档生成代码，部署时自动生成。

手动编辑对应的Json文档，该Json文档有其特定格式，相对比较复杂，手动编写难度比较大，可通过官方提供的在线编辑来实现。

Swagger的优点：

1、swagger 可以根据代码自动生成 API 文档，很好的保证了文档的时效性，做到了代码变，文档变；

2、swagger UI 呈现出来的是一份可交互式的 API 文档，我们可以直接在文档页面尝试 API 的调用，省去了准备复杂的调用参数的过程；

3、可以将swagger文档规范导入相关的工具（例如 Postman、AgileTC）, 这些工具将会为我们自动地创建自动化测试。

版权声明：本文内容由网络用户投稿，版权归原作者所有，本站不拥有其著作权，亦不承担相应法律责任。如果您发现本站中有涉嫌抄袭或描述失实的内容，请联系我们jiasou666@gmail.com 处理，核实后本网站将在24小时内删除侵权内容。