1.1 Swagger 简介

1.1.1 解决的问题

随着互联网技术的发展，现在的网站架构基本都由原来的后端渲染，变成了前后端分离的形态，而且前端技术和后端技术在各自的道路上越走越远。前端和后端的唯一联系，变成了API 接口，所以API 文档变成了前后端开发人员联系的纽带，变得越来越重要。

那么问题来了，随着代码的不断更新，开发人员在开发新的接口或者更新旧的接口后，由于开发任务的繁重，往往文档很难持续跟着更新，Swagger就是用来解决该问题的一款重要的工具，对使用接口的人来说，开发人员不需要给他们提供文档，只要告诉他们一个 Swagger 地址，即可展示在线的API接口文档，除此之外，调用接口的人员还可以在线测试接口数据，同样地，开发人员在开发接口时，同样也可以利用 Swagger在线接口文档测试接口数据，这给开发人员提供了便利。

1.1.2 Swagger官方

我们打开 Swagger官网，官方对 Swagger的定义为：

翻译成中文是：“最好的 API是使用 Swagger工具构建的”。由此可见，Swagger官方对其功能和所处的地位非常自信，由于其非常好用，所以官方对其定位也合情合理。如下图所示：

本文主要讲解在Spring Boot中如何导入Swagger2工具来展现项目中的接口文档。本节课使用的 Swagger版本为2.2.2。

1.2 Swagger2的 maven 依赖

使用 Swagger2工具，必须要导入maven依赖，当前官方最高版本是 2.8.0，我尝试了一下，个人感觉页面展示的效果不太好，而且不够紧凑，不利于操作。另外，最新版本并不一定是最稳定版本，当前我们实际项目中使用的是2.2.2 版本，该版本稳定，界面友好，所以本节课主要围绕着 2.2.2版本来展开，依赖如下：

<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>

1.3 Swagger2的配置

使用 Swagger2 需要进行配置，Spring Boot 中对Swagger2 的配置非常方便，新建一个配置类，Swagger2 的配置类上除了添加必要的 @Configuration注解外，还需要添加 @EnableSwagger2注解。

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class SwaggerConfig {

 
   @Bean //配置docket以配置Swagger具体参数
    public Docket createRestApi(Environment environment) {
		     // 设置要显示swagger的环境
		     Profiles of = Profiles.of("dev", "test");
		     // 判断当前是否处于该环境
		     // 通过 enable() 接收此参数判断是否要显示
		     boolean b = environment.acceptsProfiles(of);


        return new Docket(DocumentationType.SWAGGER_2)
                // 指定构建api文档的详细信息的方法：apiInfo()
                .apiInfo(apiInfo())
                .enable(b) //配置是否启用Swagger，如果是false，在浏览器将无法访问
                .select()
                // 指定要生成api接口的包路径，这里把controller作为包路径，生成controller中的所有接口
                .apis(RequestHandlerSelectors.basePackage("com.itcodai.course06.controller"))
                 // 配置如何通过path过滤,即这里只扫描请求以/kuang开头的接口
                 // .paths(PathSelectors.ant("/kuang/**"))
                .paths(PathSelectors.any())
                .build();
    }

    /**
     * 构建api文档的详细信息
     * @return
     */
    private ApiInfo apiInfo() {
      Contact contact = new Contact("联系人名字", "http://xxx.xxx.com/联系人访问链接", "联系人邮箱");
   return new ApiInfo(
           "Swagger学习", // 标题
           "学习演示如何配置Swagger", // 描述
           "v1.0", // 版本
           "http://terms.service.url/组织链接", // 组织链接
           contact, // 联系人信息
           "Apach 2.0 许可", // 许可
           "许可链接", // 许可连接
           new ArrayList<>()// 扩展
  );
}

在该配置类中，已经使用注释详细解释了每个方法的作用了，在此不再赘述。到此为止，我们已经配置好了 Swagger2 了。现在我们可以测试一下配置有没有生效，启动项目，在浏览器中输入 localhost:8080/swagger-ui.html，即可看到 swagger2 的接口页面，如下图所示，说明Swagger2集成成功。

结合该图，对照上面的Swagger2 配置文件中的配置，可以很明确的知道配置类中每个方法的作用。这样就很容易理解和掌握Swagger2 中的配置了，也可以看出，其实 Swagger2配置很简单。

1.4 Swagger2 的使用

上面我们已经配置好了 Swagger2，并且也启动测试了一下，功能正常，下面我们开始使用Swagger2，主要来介绍 Swagger2 中的几个常用的注解，分别在实体类上、 Controller 类上以及Controller中的方法上，最后我们看一下 Swagger2是如何在页面上呈现在线接口文档的，并且结合 Controller中的方法在接口中测试一下数据。

1.4.1 实体类注解

本节我们建一个 User实体类，主要介绍一下Swagger2中的@ApiModel和@ApiModelProperty 注解，同时为后面的测试做准备。

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;

@ApiModel(value = "用户实体类")
public class User {
    @ApiModelProperty(value = "用户唯一标识")
    private Long id;
    @ApiModelProperty(value = "用户姓名")
    private String username;
    @ApiModelProperty(value = "用户密码")
    private String password;
	// 省略set和get方法
}

解释下 @ApiModel 和 @ApiModelProperty 注解：

该注解在在线API文档中的具体效果在下文说明。

1.4.2 Controller 类中相关注解

我们写一个 TestController，再写几个接口，然后学习一下 Controller中和 Swagger2相关的注解。

import com.itcodai.course06.entiy.JsonResult;
import com.itcodai.course06.entiy.User;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/swagger")
@Api(value = "Swagger2 在线接口文档")
public class TestController {

    @GetMapping("/get/{id}")
    @ApiOperation(value = "根据用户唯一标识获取用户信息")
    public JsonResult<User> getUserInfo(@PathVariable @ApiParam(value = "用户唯一标识") Long id) {
        // 模拟数据库中根据id获取User信息
        User user = new User(id, "倪升武", "123456");
        return new JsonResult(user);
    }
}

我们来学习一下 @Api 、 @ApiOperation 和@ApiParam注解。

这里返回的是 JsonResult，是下一节课我们要学习的如何统一封装返回json 数据时的实体。以上是Swagger中最常用的 5 个注解，接下来运行一下项目工程，在浏览器中输入 localhost:8080/swagger-ui.html看一下 Swagger页面的接口状态。

可以看出，Swagger 页面对该接口的信息展示的非常全面，每个注解的作用以及展示的地方在上图中已经标明，通过页面即可知道该接口的所有信息，那么我们直接在线测试一下该接口返回的信息，输入id为1，看一下返回数据：

可以看出，直接在页面返回了json格式的数据，开发人员可以直接使用该在线接口来测试数据的正确与否，非常方便。上面是对于单个参数的输入，如果输入参数为某个对象这种情况，Swagger是什么样子呢？我们再写一个接口。

@PostMapping("/insert")
    @ApiOperation(value = "添加用户信息")
    public JsonResult<Void> insertUser(@RequestBody @ApiParam(value = "用户信息") User user) {
        // 处理添加逻辑
        return new JsonResult<>();
    }

重启项目，在浏览器中输入localhost:8080/swagger-ui.html看一下效果：

1.5 其他皮肤

我们可以导入不同的包实现不同的皮肤定义：

1.5.1 默认的访问 http://localhost:8080/swagger-ui.html

<dependency>
   <groupId>io.springfox</groupId>
   <artifactId>springfox-swagger-ui</artifactId>
   <version>2.9.2</version>
</dependency>

1.5.2 bootstrap-ui 访问 http://localhost:8080/doc.html

<!-- 引入swagger-bootstrap-ui包 /doc.html-->
<dependency>
   <groupId>com.github.xiaoymin</groupId>
   <artifactId>swagger-bootstrap-ui</artifactId>
   <version>1.9.1</version>
</dependency>

1.5.3 Layui-ui 访问http://localhost:8080/docs.html

<!-- 引入swagger-ui-layer包 /docs.html-->
<dependency>
   <groupId>com.github.caspar-chen</groupId>
   <artifactId>swagger-ui-layer</artifactId>
   <version>1.1.3</version>
</dependency>

1.5.4 mg-ui 访问http://localhost:8080/document.html

<!-- 引入swagger-ui-layer包 /document.html-->
<dependency>
   <groupId>com.zyplayer</groupId>
   <artifactId>swagger-mg-ui</artifactId>
   <version>1.0.6</version>
</dependency>

1.6 总结

OK，本节课详细分析了Swagger的优点，以及Spring Boot如何集成Swagger2，包括配置，相关注解的讲解，涉及到了实体类和接口类，以及如何使用。最后通过页面测试，体验了Swagger的强大之处，基本上是每个项目组中必备的工具之一，所以要掌握该工具的使用。

相较于传统的Postman或Curl方式测试接口，使用swagger简直就是傻瓜式操作，不需要额外说明文档(写得好本身就是文档)而且更不容易出错，只需要录入数据然后点击Execute，如果再配合自动化框架，可以说基本就不需要人为操作了。

Swagger是个优秀的工具，现在国内已经有很多的中小型互联网公司都在使用它，相较于传统的要先出Word接口文档再测试的方式，显然这样也更符合现在的快速迭代开发行情。当然了，提醒下大家在正式环境要记得关闭Swagger，一来出于安全考虑二来也可以节省运行时内存。