版权声明：本文为博主原创文章，遵循 CC 4.0 BY-SA 版权协议，转载请附上原文出处链接和本声明。
为啥使用Swagger
在实际开发过程中，由于采用的是前后端分离的开发方式，当后端开发完成后，会将接口映射地址、请求方式、接口参数、接口返回结果以及异常信息描述等等整理成一个文档，简称：接口文档。理论上文档中的接口应该是和项目中的接口完全吻合的，但是在经过无数次的bug修复和更新迭代，难免会有漏改或者错改接口文档的情况，因此手写文档变得就十分鸡肋了。
有问题就会有优秀的团队出来解决问题，Swagger就是用来解决它的免费框架，它被用于生成、描述、调用和可视化RESTful风格的Web服务。具备图形化界面，方便在浏览器模拟请求进行接口自测。不过它也有缺点，就是代码入侵较为严重，需要依赖注解的方式实现。
SpringBoot整合Swagger2流程
1.创建SpringBoot项目，添加Swagger依赖包。
<!-- 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.Swagger配置文件
/**
* FileName: SwaggerConfig
* Author: RollerRunning
* Date: 2019/10/23 4:15 PM
* Description: Swagger配置文件
*/
@Configuration
@EnableSwagger2
public class SwaggerConfig extends WebMvcConfigurationSupport {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
//扫描该包下的所有需要在Swagger中展示的API，@ApiIgnore注解标注的除外
.apis(RequestHandlerSelectors.basePackage("com.example"))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
//API标题
.title("SpringBoot系列教程之整合Swagger2")
//API描述
.description("仅作为学习记录使用，如有问题多多指教")
//版本号
.version("1.0")
.build();
}
/**
* 手动设置swagger中的静态资源信息
* @param registry
*/
@Override
protected void addResourceHandlers(ResourceHandlerRegistry registry) {
// 解决静态资源无法访问
registry.addResourceHandler("/**")
.addResourceLocations("classpath:/static/");
// 解决swagger无法访问
registry.addResourceHandler("/swagger-ui.html")
.addResourceLocations("classpath:/META-INF/resources/");
// 解决swagger的js文件无法访问
registry.addResourceHandler("/webjars/**")
.addResourceLocations("classpath:/META-INF/resources/webjars/");
}
}
3.接口添加注解
/**
* FileName: HelloWorldController
* Author: RollerRunning
*/
@Api(value = "HelloWorldController", tags = "整合Swagger的测试接口")
@RestController
public class HelloWorldController {
private static final Logger logger = LoggerFactory.getLogger(HelloWorldController.class);
@Autowired
private UserService userService;
/**
* @param userName, address, addTime
* @return void
* @description 新增用户信息
**/
@ApiOperation(value = "新增用户数据", produces = MediaType.APPLICATION_JSON_VALUE,
extensions = @Extension(properties = @ExtensionProperty(name = "author",
value = "RollerRunning111")))
@ApiImplicitParams({
@ApiImplicitParam(name = "userName", value = "用户名", defaultValue = "张三"),
@ApiImplicitParam(name = "address", value = "用户地址", defaultValue = "北京市")
})
@PostMapping("add")
public String hello(String userName, String address) {
System.out.println("接收到前端传递的参数信息，userName=" + userName + ", address=" + address);
userService.addUser(userName, address, new Date());
return "success";
}
}
其中ApiOperation里的描述信息，会展示在Swagger的图形化web界面当中，作为对应接口的描述。
4.实体类添加注解
/**
* FileName: UserInfo
* Author: RollerRunning
* Date: 2019/8/6 6:02 PM
* Description:
*/
@ApiModel
public class UserInfo implements Serializable {
@ApiModelProperty(value = "用户id")
private Integer id;
@ApiModelProperty(value = "用户名")
private String userName;
@ApiModelProperty(value = "住址")
private String address;
private Date addTime;
....
}
其中ApiModelProperty里的描述会展示在前端界面的models模块中。
5.访问Swagger并做接口测试
通过以上4部的配置，基本完成了Swagger的常用配置信息，访问http://localhost:8080/swagger-ui.html即可访问到Swagger的接口管理界面，如下图：
此时，点击不同的接口，界面展开以后，点击Try it out后可以实现模拟get/post访问接口，在最下方的models模块中会展示实体类的字段及相关描述信息。
6.Swagger常用注解说明
| 注解名称 | 说明 |
|---|---|
| @Api | 标注在Controller类上，tags和value的值会展示在web界面对应接口描述上 |
| @ApiOperation | 标注在具体接口方法上，用于描述具体方法的特性 |
| @ApiImplicitParams | 标注在方法上，用于描述对应接口参数的意义 |
| @ApiModel | 标注于实体类上 |
| @ApiModelProperty | 标注于实体类属性上，用于说明各属性含义 |
| @ApiIgnore | 用于标注在不想被Swagger扫描的类或者方法及属性上 |
总结
配置整合Swagger这部分，内容虽然不多，但在项目开发过程中属于一劳永逸的配置，能理解常见的几个注解及使用方法即可。本文内容参考自官网以及网络上各位大神们的博客，如有雷同，只怪这部分内容的确没什么写的，哈哈哈~~~感谢！