勿忘初心

个人签名

530篇博客

接口文档神器Swagger(上篇)

勿忘初心2018-09-04 09:54

作者:李哲


接口文档管理一直是一个让人头疼的问题,伴随着各种接口文档管理平台涌现,如阿里开源的rapShowDocsosoapi,等等(网上能找到很多这种管理平台,包括我们自己做的idoc)。这些平台都是一个共同特点,创建文档,编辑,保存文档,一些功能强大的还有mock,统计接口信息等功能,所以这些平台更像一个接口文档的存储管理系统,可以方便人们查看、编辑文档。然而接口一般都是经常变化(添加、删除参数),这就需要接口编写者及时更新文档,否则文档将失去意义,但是频繁去更新文档也会花费开发不少时间。Swagger的出现在某种程度上解决了这些问题,Swagger提供了一套完整的接口文档解决方案,其功能非常强大,下面将从Swagger简单介绍和使用、Swagger-springmvc原理解析、Swagger其他功能等方面介绍。

一、Swagger介绍和使用

1、 什么是swagger

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

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

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

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

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

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

2、 如何编写API文档

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

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

3)通过swagger的各种语言的插件,可以通过配置及少量代码,生成接口文档及测试界面。通过yamljson书写的是静态文档,需要书写文档中需要的内容,详细写法可参考:https://www.gitbook.com/book/huangwenchao/swagger/details,完成后可以通过可视化页面显示接口文档。但要完成整个项目的接口文档书写也非常耗时,如果是后台开发,可以通过简单配置实现文档的自动生成。

3、 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中是否添加了SwaggerConfigbean

4、 Springboot项目中使用swagger2

相对于springmvc中添加swaggerspringboot中更加简单。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,通过简单的方式自动生成接口文档,而且以可视化页面的形式展现,非常灵活方便。

       下面对swaggerspring中使用的一些常用注解进行说明:

  • ApiApiIgnore
  • ApiModel
  • ApiModelProperty
  • ApiOperation
  • ApiParamApiImplicitParamApiImplicitParams
  • 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

本文来自网易实践者社区,经作者李哲授权发布