Swagger介绍和应用

1、 什么是Swagger

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化RESTful风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。Swagger让部署管理和使用功能强大的API变得非常简单。

Swagger采用Open API规范，Open API规范这类API定义语言能够帮助你更简单、快速的表述API，尤其是在API的设计阶段作用特别突出。一旦编写完成，API文档可以作为：

· 需求和系统特性描述的根据

· 前后台查询、讨论、自测的基础

· 部分或者全部代码自动生成的根据

· 其他重要的作用，比如开放平台开发者的手册

2、 如何编写API文档

1）、定义YAML文件，然后可以生成各种语言的代码框架，对于后台程序员来说，较少人会愿意写出一堆YAML格式。

2）、定义JSON格式文件，按照swagger文档书写规范编写文档，和YAML一样只是两种不同格式。

3）、通过swagger的各种语言的插件，可以通过配置及少量代码，生成接口文档及测试界面。通过yaml或json书写的是静态文档，完成后可以通过可视化页面显示接口文档。但要完成整个项目的接口文档书写也非常耗时，如果是后台开发，可以通过简单配置实现文档的自动生成。

3、Swagger在API项目中的应用

Eolinker是我们公司内部用的一个集成化的接口管理工具，包含开发、测试和文档的功能，打包好的架构也少了很多代码输入的工作。下面用它来演示一下和Swagger的对接。
www.eolinker.com

1）、在Eolinker界面直接导入json格式的Swagger文件；

2）、直接对写好的接口进行测试；

可以直接在详情里修改单独某个接口的参数，且接口文档的内容是跟随接口改动实时变化的。相对于静态的文档每次改动都需要开发更新文档，这无疑是非常好的解决方案。

3）、可以导出多种格式的文档；

有时候对外的项目对接，对方不是用的Swagger，也可以导出成其他格式的文档，这个是我比较惊喜的点。