接口文档神器Swagger（上篇）

本文来自网易云社区

做者：李哲

接口文档管理一直是一个让人头疼的问题，伴随着各类接口文档管理平台涌现，如阿里开源的rap，ShowDoc，sosoapi，等等（网上能找到不少这种管理平台，包括咱们本身作的idoc）。这些平台都是一个共同特色，建立文档，编辑，保存文档，一些功能强大的还有mock，统计接口信息等功能，因此这些平台更像一个接口文档的存储管理系统，能够方便人们查看、编辑文档。然而接口通常都是常常变化（添加、删除参数），这就须要接口编写者及时更新文档，不然文档将失去意义，可是频繁去更新文档也会花费开发很多时间。Swagger的出如今某种程度上解决了这些问题，Swagger提供了一套完整的接口文档解决方案，其功能很是强大，下面将从Swagger简单介绍和使用、Swagger-springmvc原理解析、Swagger其余功能等方面介绍。

1、Swagger介绍和使用

一、 什么是swagger

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

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

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

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

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

·  其余重要的做用，好比开放平台开发者的手册

二、 如何编写API文档

（1）定义YAML文件，而后能够生成各类语言的代码框架，对于后台程序员来讲，较少人会愿意写出一堆YAML格式。

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

（3）经过swagger的各类语言的插件，能够经过配置及少许代码，生成接口文档及测试界面。经过yaml或json书写的是静态文档，须要书写文档中须要的内容，详细写法可参考：https://www.gitbook.com/book/huangwenchao/swagger/details，完成后能够经过可视化页面显示接口文档。但要完成整个项目的接口文档书写也很是耗时，若是是后台开发，能够经过简单配置实现文档的自动生成。

三、 Springmvc项目中使用swagger

1） 添加maven依赖

   

<dependency>

         <groupId>com.mangofactory</groupId>

         <artifactId>swagger-springmvc</artifactId>

         <version>1.0.2</version>

      </dependency>

2） 定义一个swagger配置类，添加以下注解，具体内容可参考网上demo

3） 在spring配置文件中将写的config类添加一个bean

4） 在controller中接口处添加swagger注解和相应参数

5） Swagger UI配置

从https://github.com/swagger-api/swagger-ui 获取3.0版本如下，2.0版本以上。其全部的dist目录下东西放到须要集成的项目里，本文放入src/main/webapp/WEB -INF/docs/ 目录下。

  修改swagger/index.html文件，默认是从链接http://petstore.swagger.io/v2/ swagger.json获取 API 的 JSON，这里须要将url内容修改成http://{ip}:{port}/{project Name}/api-docs的形式，{}中的内容根据具体状况填写。好比本文的url值为：http://localhost/quality /docs/api-docs。全部工做完成后，在浏览器中输入上述url地址可获得以下页面（注：该页面是swagger官网示例）。

接口详情以下图所示：

能够根据请求参数访问接口，若是网络通畅将返回接口的response结果，在该页面能够看到接口的基本详情，并且若是后台接口发生变化，该页面中的信息也会随着变化，这样接口的内容就是实时变化的，相对于静态的文档每次改动都须要开发更新文档的方式，该方式无疑是很是好的解决方案。

若是过程当中发现没有达到预期的结果，请检查swagger ui位置是否正确；spring中是否添加了SwaggerConfig的bean。

四、 Springboot项目中使用swagger2

相对于springmvc中添加swagger，springboot中更加简单。Springboot中许多配置是默认的，不用太多配置就能完成swagger的接入。具体流程以下：

1） 添加maven依赖

  

<!-- swagger框架 -->

      <dependency>

         <groupId>io.springfox</groupId>

         <artifactId>springfox-swagger2</artifactId>

         <version>2.2.2</version>

      </dependency>

      <dependency>

         <groupId>io.springfox</groupId>

         <artifactId>springfox-swagger-ui</artifactId>

         <version>2.2.2</version>

      </dependency>

2）  建立swagger2配置类，该类和springmvc中的不太同样，具体可参考swagger官网。配置中经过@Configuration注解，让Spring来加载该类配置。再经过@EnableSwagger2注解来启用Swagger2。

3）  和springmvc同样，在controller接口中编写swagger相关的注解来标识接口信息。以下所示，经过@ApiOperation注解来给API增长说明、经过@ApiImplicitParams、@ApiImplicitParam注解来给参数增长说明。

4）  完成上述代码添加上，启动Spring Boot程序，访问：http://localhost:8080/swagger- ui.html。就能看到前文所展现的RESTful API的页面。咱们能够再打开具体的API请求，以POST类型的/users请求为例，可找到上述代码中咱们配置的Notes信息以及参数user的描述信息，以下图所示。

经过简单的配置改动，spring就能结合swagger，经过简单的方式自动生成接口文档，并且以可视化页面的形式展示，很是灵活方便。

       下面对swagger在spring中使用的一些经常使用注解进行说明：

• Api、ApiIgnore

• ApiModel

• ApiModelProperty

• ApiOperation

• ApiParam、ApiImplicitParam、ApiImplicitParams

• ApiResponse

• ApiResponses

• ResponseHeader

1）  Api注解用于类上，说明该类的做用。能够标记一个Controller类作为swagger 文档资源。与Controller注解并列使用。

            @Api(value = "/user", description = "Operations about user")

属性以下：

2） ApiOperation注解，用在方法上，说明方法的做用，与Controller中的方法并列使用。

3） ApiParam注解用在@ApiImplicitParams的方法里边，属性配置：

4） ApiResponse注解用于响应配置，与Controller中的方法并列使用。属性配置：

5） ApiResponses注解中包含ApiResponse，用于描述一组ApiResponse值。

6） ResponseHeader注解用于设置响应头，与Controller中的方法并列使用。 属性配置：

7） ApiImplicitParams注解用于方法上包含一组参数说明。

8） ApiImplicitParam注解用于描述请求参数，根据不一样的paramType类型，请求的参数来源不一样。属性及取值以下：

9）  ApiModel注解用于表示对类进行说明，描述一个Model的信息，表示参数用实体类接收。

10）ApiModelProperty注解用于方法、字段，表示对model属性的说明或者数据操做更改，配合ApiModel一块儿使用。

11）ApiIgnore注解用于类或方法上，表示不须要swagger处理。

Swagger提供的注解还有其余一些，此处不作解释（并且高版本中的注解可能不太同样），能够经过官方文档或源码查阅，基本经常使用的注解就是这些，详细的使用方法能够网上查看。若是熟悉了这些注解就能够很快的表示后台代码接口的信息，而后经过页面的形式展现出来。可是swagger是如何结合spring经过简单的配置、添加注解的方式就将接口的信息展示出来。下面将看看swagger为何这么神奇。

 

相关阅读：接口文档神器Swagger（下篇）

网易云大礼包：https://www.163yun.com/gift

本文来自网易云社区，经做者李哲受权发布

相关文章：
【推荐】 大数据技术在金融行业的应用前景