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
持续更新！！！
