Springboot使用Swagger

前言

Spring Boot框架是目前非常流行的微服务框架，我们很多情况下使用它来提供Rest API。而对于Rest API来说很重要的一部分内容就是文档，Swagger为我们提供了一套通过代码和注解自动生成文档的方法，这一点对于保证API文档的及时性将有很大的帮助。本文将使用Swagger 2规范的Springfox实现来了解如何在Spring Boot项目中使用Swagger，主要包含了如何使用Swagger自动生成文档、使用Swagger文档以及Swagger相关的一些高级配置和注解。

Swagger 简介

Swagger是一套基于OpenAPI规范构建的开源工具，可以帮助我们设计、构建、记录以及使用Rest API。Swagger主要包含了以下三个部分：

• Swagger Editor：基于浏览器的编辑器，我们可以使用它编写我们OpenAPI规范。
• Swagger UI：它会将我们编写的OpenAPI规范呈现为交互式的API文档，后文我将使用浏览器来查看并且操作我们的Rest API。
• Swagger Codegen：它可以通过为OpenAPI（以前称为Swagger）规范定义的任何API生成服务器存根和客户端SDK来简化构建过程。

为什么要使用Swagger

现在有很多公司都采取前后端分离的开发模式，前端和后端的工作由不同的工程师完成。在这种开发模式下，维持一份及时更新且完整的Rest API文档将会极大的提高我们的工作效率。传统意义上的文档都是后端开发人员手动编写的，相信大家也都知道这种方式很难保证文档的及时性，这种文档久而久之也就会失去其参考意义，反而还会加大我们的沟通成本。而Swagger给我们提供了一个全新的维护API文档的方式，下面我们就来了解一下它的优点：

• 代码变，文档变。只需要少量的注解，Swagger就可以根据代码自动生成API文档，很好的保证了文档的时效性。
• 跨语言性，支持40多种语言。
• Swagger UI呈现出来的是一份可交互式的API文档，我们可以直接在文档页面尝试API的调用，省去了准备复杂的调用参数的过程。
• 还可以将文档规范导入相关的工具（例如SoapUI）, 这些工具将会为我们自动地创建自动化测试。
  以上这些优点足以说明我们为什么要使用Swagger了，您是否已经对Swagger产生了浓厚的兴趣了呢？下面我们就将一步一步地在Spring Boot项目中集成和使用Swagger，让我们从准备一个Spring Boot的Web项目开始吧。

准备Spring Boot Web项目

准备一个基础的Spring Boot的Web项目，并且提供后面所需要的所有API。

创建一个空的Spring Boot项目

您可以通过Spring Initializr页面生成一个空的Spring Boot项目，当然也可以下载springboot-pom.xml文件，然后使用Maven构建一个Spring Boot项目。项目创建完成后，为了方便后面代码的编写可以将其导入到自己喜欢的IDE中，我这里使用ntelli IDEA打开。

添加依赖

由于创建的是一个Web项目，所以我们需要依赖Spring Boot的Web组件和Swagger的相关jar包，只需要在pom.xml增加如下内容即可：

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>
    <dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>
    <dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

编写接口

1.首先我们创建三个包：cn.cj.swagger.controller、cn.cj.swagger.testcontroller以及cn.cj.swagger.model。
2.在controller包下新建UserController.java类，在testcontroller包下新建TestController.java类，在model包下新建User.java类。
3.UserController提供用户的增、删、改、查四个接口，TestContrller提供一个测试接口。

@RestController
@RequestMapping("/user")
@Api(tags = "用户相关接口", description = "提供用户相关的Rest API")
public class UserController {

    @ApiOperation("新增用户接口")
    @PostMapping("/add")
    public boolean addUser(@RequestBody User user) {
        return false;
    }

    @ApiOperation("通过id查找用户接口")
    @GetMapping("/find/{id}")
    public User findById(@PathVariable("id") int id) {
        return new User();
    }

    @ApiOperation("更新用户信息接口")
    @PutMapping("/update")
    public boolean update(@RequestBody User user) {
        return true;
    }

    @ApiOperation("删除用户接口")
    @DeleteMapping("/delete/{id}")
    @ApiIgnore
    public boolean delete(@PathVariable("id") int id) {
        return true;
    }
}

Java配置

Springfox提供了一个Docket对象，让我们可以灵活的配置Swagger的各项属性。下面我们新建一个com.cj.swagger.config.SwaggerConfig.java类，并增加如下内容:

@Configuration
@EnableSwagger2
public class SwaggerConfig {
       @Bean
    public Docket api()
    {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.cj.swagger"))
                .paths(PathSelectors.any())
                .build()
                .apiInfo(apiInfo())
                ;
    }
}

注意: @Configuration是告诉Spring Boot需要加载这个配置类，@EnableSwagger2是启用Swagger2，如果没加的话就看不到效果。

访问http://localhost:8080/swagger-ui.html就能看到效果

高级配置

文档相关描述配置

1.通过在控制器类上增加@Api注解，可以给控制器增加描述和标签信息。

@Api(tags = "用户相关接口", description = "提供用户相关的Rest API")
public class UserController

2.通过在接口方法上增加@ApiOperation注解来展开对接口的描述，当然这个注解还可以指定很多内容，我们在下面的相关注解说明章节中详细解释。

@ApiOperation("新增用户接口")
@PostMapping("/add")
public boolean addUser(@RequestBody User user) {
    return false;
}

3.实体描述，我们可以通过@ApiModel和@ ApiModelProperty注解来对我们API中所涉及到的对象做描述。

@ApiModel("用户实体")
public class User {
    @ApiModelProperty("用户id")
private int id;
}

4.文档信息配置，Swagger还支持设置一些文档的版本号、联系人邮箱、网站、版权、开源协议等等信息，但与上面几条不同的是这些信息不是通过注解配置，而是通过创建一个ApiInfo对象，并且使用Docket.appInfo()方法来设置，我们在SwaggerConfig.java类中新增如下内容即可。

 @Bean
    public Docket api()
    {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.cj.swagger"))
                .paths(PathSelectors.any())
                .build()
                .apiInfo(apiInfo())
                ;
    }
    private ApiInfo apiInfo()
    {
        return  new ApiInfo(
                "Spring Boot项目集成Swagger实例文档",
                 "我的博客网站：hcj123123.oschina.io，欢迎大家访问。",
                "API V1.0",
                "Terms of service",
                new Contact("jackey", "hcj123123.oschina.io", "1656927346@qq.com"),
                "Apache", "http://www.apache.org/", Collections.emptyList());

    }

经过上面的步骤，文档就变成了下面样子。

接口过滤

有些时候我们并不是希望所有的Rest API都呈现在文档上，这种情况下Swagger2提供给我们了两种方式配置，一种是基于@ApiIgnore注解，另一种是在Docket上增加筛选。

1.@ApiIgnore注解。
如果想在文档中屏蔽掉删除用户的接口（user/delete），那么只需要在删除用户的方法上加上@ApiIgnore即可。

@ApiIgnore
public boolean delete(@PathVariable("id") int id)

2.在Docket上增加筛选。Docket类提供了apis()和paths()两个方法来帮助我们在不同级别上过滤接口：

• apis()：这种方式我们可以通过指定包名的方式，让Swagger只去某些包下面扫描。
• paths()：这种方式可以通过筛选API的url来进行过滤。
  在集成Swagger2的章节中我们这两个方法指定的都是扫描所有，没有指定任何过滤条件。如果我们在我们修改之前定义的Docket对象的apis()方法和paths()方法为下面的内容，那么接口文档将只会展示/user/add和/user/find/{id}两个接口。

.apis(RequestHandlerSelectors.basePackage("com.cj.swagger")).paths(Predicates.or(PathSelectors.ant("/user/add"),        PathSelectors.ant("/user/find/*")))

Swagger UI的使用

接口查看

SwaggerUI会以列表的方式展示所有扫描到的接口，初始状态是收缩的，我们只需要点击展开就好，而且会在左边标识接口的请求方式（GET,POST,PUT,DELETE等等）。

接口调用

如下图所示，点击接口展开后页面右上角的Try it out按钮后，页面会变成如图所示：

SwaggerUI会给我们自动填充请求参数的数据结构，我们需要做的只是点击Execute即可发起调用

Model

如下图所示，SwaggerUI会通过我们在实体上使用的@ApiModel注解以及@ApiModelProperty注解来自动补充实体以及其属性的描述和备注。

相关注解说明

Controller相关注解

注解属性	类型	描述
tags	String[]	控制器标签。
description	String	控制器描述（该字段被申明为过期）。

接口相关注解

1.@ApiOperation: 可设置对接口的描述。

注解属性	类型	描述
value	String	接口说明。
notes	String	接口发布说明。
tags	Stirng[]	标签。
response	Class<?>	接口返回类型。
httpMethod	String	接口请求方式。

2.@ApiIgnore: Swagger文档不会显示拥有该注解的接口。
3.@ApiImplicitParams: 用于描述接口的非对象参数集。
4.@ApiImplicitParam: 用于描述接口的非对象参数，一般与@ApiImplicitParams组合使用。

注解属性	描述
paramType	查询参数类型，实际上就是参数放在那里。取值： path：以地址的形式提交数据，根据id查询用户的接口就是这种形式传参。 query：Query string的方式传参。 header：以流的形式提交。 form：以Form表单的形式提交。
dataType	参数的数据类型。取值：Long，String
name	参数名字。
value	参数意义的描述。
required	是否必填。取值：true：必填参数，false：非必填参数。

Model相关注解

1.@ApiModel: 可设置接口相关实体的描述。
2.@ApiModelProperty: 可设置实体属性的相关描述。

注解属性	类型	描述
value	String	字段说明。
name	String	重写字段名称。
dataType	Stirng	重写字段类型。
required	boolean	是否必填。
example	Stirng	举例说明。
hidden	boolean	是否在文档中隐藏该字段。
allowEmptyValue	boolean	是否允许为空。
allowableValues	String	该字段允许的值，当我们API的某个参数为枚举类型时，使用这个属性就可以清楚地告诉API使用者该参数所能允许传入的值。