Spring Boot学习（十八）：Spring Boot整合Swagger2，原来这么简单

前言

Spring Boot系列: 点击查看Spring Boot系列文章

Swagger2

在现在，前后端分离已经成为互联网项目一种主流的开发方式，前端与后端交给不同的人员开发，其中交流API规定，写接口文档也成了家常便饭。我们知道，接口总是不断的在变动，如果每次都人为修改，是很浪费时间的，所以Swagger2 诞生了。Swagger2 就可以很好地解决这个问题，它可以动态生成Api接口文档，降低我们的沟通成本，最重要还免费。

1、pom文件导入依赖，我使用的是最新的2.9.2，大家根据自己需求来选择版本

        <!-- swagger依赖 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>
        <!-- swagger原生ui  -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
        </dependency>

2、创建swagger2配置类，进行swagger2配置

配置很简单，只需要在配置类提供一个Docket的Bean，我们在Docket的Bean中配置swagger的信息

注：Docket中的有一个apiInfo属性，主要配置一下Swagger2文档网站的信息，例如网站的title，网站的描述，联系人的信息，使用的协议等等。

例：

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                //过select()函数返回一个ApiSelectorBuilder实例,用来控制哪些接口暴露给Swagger来展现
                .select()
                //api接口包扫描路径
                .apis(RequestHandlerSelectors.basePackage("com.example.demo.controller"))
                //可以根据url路径设置哪些请求加入文档，忽略哪些请求,PathSelectors.any()为全部允许
                .paths(PathSelectors.any())
                .build();
    }
    //配置在线文档的基本信息
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                //设置文档的标题
                .title("springboot利用swagger构建api文档")
                //设置文档的描述
                .description("api文档")
                //设置文档的版本信息
                .version("1.0")
                .build();
    }
}

@EnableSwagger2注解启用Swagger2，然后配置一个Docket Bean，这个Bean中，配置扫描接口的位置等信息。

注意：SwaggerConfig配置类最好放在和启动类同级的目录下，这样才可以扫描到我们所有想要扫描的接口

启动项目，输入http://localhost:8080/swagger-ui.html，能够看到如下页面，说明已经配置成功了

访问地址：http://项目实际地址/swagger-ui.html

使用Swagger2

Swagger2常用注解

@Api：用在请求的类上，说明该类的作用
tags=“说明该类的作用”

@ApiOperation：用在请求的方法上，说明方法的作用
value=“说明方法的作用”
notes=“方法的备注说明”

@ApiImplicitParams：用在请求的方法上，包含一组参数说明。@ApiImplicitParams包含多个@ApiImplicitParam

@ApiImplicitParam：用在 @ApiImplicitParams 注解中，指定一个请求参数的配置信息
name：参数名
value：参数的汉字说明、解释
required：参数是否必须传
paramType：参数放在哪个地方
· header --> 请求参数的获取：@RequestHeader
· query --> 请求参数的获取：@RequestParam
· path（用于restful接口）–> 请求参数的获取：@PathVariable
· body（不常用）
· form（不常用）
dataType：参数类型，默认String，其它值dataType=“Integer”
defaultValue：参数的默认值
例：@ApiImplicitParam(name = “id”, value = “用户ID”, required = true, dataType = “Long”，paramType = "query ")；

@ApiModel：用于model类上，表示这是一个model类（一般用在使用@RequestBody传参，请求参数无法使用@ApiImplicitParam注解进行描述的时候）

@ApiModelProperty：用在属性上，描述model类的属性

@ApiResponses：用于请求的方法上，表示一组响应

@ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息
code：数字，例如500
message：信息，例如"代码出错"
response：抛出异常的类

使用例子

我们先创建一个User的Model类

@Data
@ApiModel(value = "用户信息")
public class User {
    @ApiModelProperty(value = "用户id")
    private Integer id;
    @ApiModelProperty(value = "用户名")
    private String username;
}

然后创建一个controller接口

@RestController
@Api(tags = "用户相关接口")
@RequestMapping("/user")
public class UserController {

    @PostMapping("/getUser")
    @ApiOperation("获取用户信息接口")
    public User getUser(){
        User user=new User();
        user.setId(1L);
        user.setUsername("m");
        return user;
    }

}

创建完成之后，我们启动项目，访问swwager网址，就可以看到接口信息了（接口请求方式，接口地址以及接口的名字等，点开一个接口，就可以看到该接口的入参和出参等信息）

除了可以查看接口信息之外，我们还可以点击右上角的Try it out，进行接口测试

输入入参，点击Execute，即可执行该接口

然后我们就可以看到响应信息了