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文件;

Swagger介绍和应用_第1张图片

2)、直接对写好的接口进行测试;

Swagger介绍和应用_第2张图片

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

3)、可以导出多种格式的文档;

Swagger介绍和应用_第3张图片

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

你可能感兴趣的