SpringBoot的整合（四、整合Swagger2）

想必大家也搜索过Swagger的具体作用，这里不做过多阐述，简单总结一下，Swagger就是用来帮助我们整理接口信息的，我们通过Swagger提供的注解，来对接口和model进行描述。

下面直接上干货，springboot整合Swagger2。

（1）搭建一个springboot框架项目

首先，我们需要搭建好一个springboot的框架，如果不会搭建，可以参考我的一篇框架搭建入门文章，里面有详细的代码，希望可以帮助到大家：SpringBoot的整合（三、整合mybatis）

（2）修改pom.xml文件中

之后我们在pom.xml中添加Swagger相关的依赖

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

（3）写一个配置类

之后需要我们提供一个配置类，首先通过@EnableSwagger2注解启用Swagger2，然后配置一个Docket Bean，这个Bean中，配置映射路径和要扫描的接口的位置，在apiInfo中，主要配置一下Swagger2文档网站的信息，例如网站的title，网站的描述，联系人的信息，使用的协议等等。这样，Swagger2就算是配置成功了。要注意修改里面的扫描包的位置。位置随意。

package com.flyinghome.tm.config;

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.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .pathMapping("/")
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.flyinghome.tm"))
                .paths(PathSelectors.any())
                .build().apiInfo(new ApiInfoBuilder()
                        .title("SpringBoot整合Swagger测试")
                        .description("SpringBoot整合Swagger，详细信息......")
                        .version("9.0")
                        .contact(new Contact("啊啊啊啊","blog.csdn.net","aaa@gmail.com"))
                        .license("The Apache License")
                        .licenseUrl("http://www.baidu.com")
                        .build());
    }
}

我的这里是随便建了一个config文件夹放入配置类

（4）启动项目

最后启动项目，浏览器中输入：http://localhost:8080/swagger-ui.html，能够看到如下页面说明成功了。

（5）添加Swagger相关注解

此时我们开始添加注解：

首先在类上添加Api注解，方法上添加ApiOperation注解来对类和方法进行描述

@RestController
@RequestMapping(value = "/test")
@Api(tags = "用户crud测试")
public class UserController {

    @Autowired
    private UserService userService;

    /**
     * Swagger测试
     */
    @PostMapping("/testSwagger")
    @ApiOperation("Swagger的测试")
    public User getUserByid(String name,String password){
        User user = new User();
        user.setName(name);
        user.setPassword(password);
        return user;
    }
    
}

在model类中使用@ApiModelProperty注解来描述各个属性

package com.flyinghome.tm.model;

import io.swagger.annotations.ApiModelProperty;
import lombok.Data;

@Data
public class User {
    @ApiModelProperty(value = "用户id")
    private String id;
    @ApiModelProperty(value = "用户姓名")
    private String name;
    @ApiModelProperty(value = "用户密码")
    private String password;
    @ApiModelProperty(value = "页码")
    private String pageno;
    @ApiModelProperty(value = "数量")
    private String pagesize;
}

此时重新启动浏览器刷新项目，可以看到页面有了变化。即我们刚才填写的备注都显示在了对应的位置上。

（6）使用Swagger调试代码

步骤5的图中我们可以看到，在controller类中，我们有很多的接口，每个接口前面的图标即是请求的类型，可以看出图里的类中，有一个post请求和n个get请求，我们可以点击对应的接口，输入参数，进行调试。具体步骤如下：

 

（7）补充Swagger注解

Swagger的注解不仅仅是我上面所写的那些，还有一部分，下面我总结一些常用的Swagger注解，大家用来参考：

1. @Api注解可以用来标记当前Controller的功能。

2. @ApiOperation注解用来标记一个方法的作用。

3. @ApiImplicitParam注解用来描述一个参数，可以配置参数的中文含义，也可以给参数设置默认值，这样在接口测试的时候可以避免手动输入。

4. 如果有多个参数，则需要使用多个@ApiImplicitParam注解来描述，多个@ApiImplicitParam注解需要放在一个@ApiImplicitParams注解中。

5. 需要注意的是，@ApiImplicitParam注解中虽然可以指定参数是必填的，但是却不能代替@RequestParam(required = true)，前者的必填只是在Swagger2框架内必填，抛弃了Swagger2，这个限制就没用了，所以假如开发者需要指定一个参数必填，@RequestParam(required = true)注解还是不能省略。

6. 如果参数是一个对象（例如上文的更新接口），对于参数的描述也可以放在实体类中。

参考：

1. https://blog.csdn.net/u012702547/article/details/88775298

2. https://blog.csdn.net/miachen520/article/details/95722887

持续更新！！！