随着技术的不断发展，现在开发的模式大部分都是前后端分离，为了跟前端同事沟通方便，大部分写后端的朋友都要写接口文档，写接口文档确实减少了跟前端同事很多不必要的沟通，但是这样就真的没有一点缺点了吗？
当接口稍微改动就得马上更新文档，然后得马上给前端发一份，这样有时候就会造成文档更新交流不及时，前端接收的文档就会多，不好管理。
就算文档更新及时了、前端也整理好了文档，也不能直接在线测试接口，通常都需要第三方插件来测试，例如postman。
但是今天我给大家介绍的swagger2就不需要，它不仅能自动生成接口文档，还能在线测试接口是否正常！
废话不多说，咱们直接进入主题，今天我们就用springboot2来整合swagger2，直接带你们应用起来。
先说一下我使用的架构和版本信息，springboot版本为2.1.6，swagger的版本为2.8，数据底层使用的是mybatis，mybatis的版本为1.3.2。
第一步：导入依赖
<!-- 导入swagger2的包-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.8.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.8.0</version>
</dependency>
第二步：配置Swagger类
/**
* 整合swagger2
*/
@Configuration
@EnableSwagger2
public class SwaggerConfig extends WebMvcConfigurationSupport {
/**
* 设置一个开关，生产版本为false，关闭swagger
*/
@Value("${swagger.ebable}")
private boolean ebable;
@Bean
public Docket createRestApi(){
return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).
enable(ebable).select().apis(RequestHandlerSelectors.basePackage("com.demo.controller")). //扫描包
paths(PathSelectors.any()).build();
//可以设置为扫描多个包
/**
* com.google.common.base.Predicate<RequestHandler> selector1 = RequestHandlerSelectors.basePackage("设置你要扫描的包路径");
* com.google.common.base.Predicate<RequestHandler> selector2 = RequestHandlerSelectors.basePackage("设置你要扫描的包路径");
* createRestApi这样写即可。
* @Bean
* public Docket createRestApi(){
* return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).
* enable(ebable).select().
* apis(Predicates.or(selector1,selector2)).
* paths(PathSelectors.any()).build();
* }
*/
}
@SuppressWarnings("deprecation")
public ApiInfo apiInfo(){
return new ApiInfoBuilder().title("接口文档").
description("服务端通用接口").version("1.0").build();
}
/**
* 一定要写这个方法，不然访问swagger-ui.html页面会404
* @param registry
*/
@Override
protected void addResourceHandlers(ResourceHandlerRegistry registry) {
registry.addResourceHandler("/**").
addResourceLocations("classpath:/META-INF/resources/").
setCachePeriod(0);
}
}
SwaggerConfig类上有一个ebable属性，我们可以在yml文件上定义一下，当我们要上生产环境时，把这个ebable属性为false，swagger就关闭了。
swagger: ##给swagger设置一个开关
ebable: true
配置好了，咱们来写一个controller。
@RestController
@Api(description = "关于用户接口",value = "用户接口",tags = {"用户接口"}) //使用@Api来修饰类
public class UserController {
@Autowired
private UserService userService;
@GetMapping("/getUser/{userId}") //使用RestFul风格
//使用@ApiOperation注解来修饰接口
@ApiOperation(value = "通过用户Id来获取用户信息",notes = "RestFul风格，需要传用户Id")
//使用ApiImplcitParam修饰接口参数
@ApiImplicitParam(name = "userId",value = "用户Id",required = true)
public User getUserById(@PathVariable("userId") Integer userId){
return userService.selectById(userId);
}
}
依赖也导入了，配置也配好了，接口也写好了，咱们来启动一下这个程序吧。
启动成功后，直接访问localhost:8080/swagger-ui.html，就能看到swagger为咱们生成的接口文档了。
springboot2+swagger2的整合就到此结束了。但是swagger2还有一些注解没给大家介绍，因为swagger2是通过各种注解来生成接口文档的，下面就给大家介绍介绍swagger2的注解。
@Api：修饰整个类，描述Controller的作用
@ApiOperation：描述一个类的一个方法，或者说一个接
@ApiParam：单个参数描述
@ApiModel：用对象来接收参数
@ApiProperty：用对象接收参数时，描述对象的一个字段
@ApiResponse：HTTP响应其中1个描述
@ApiResponses：HTTP响应整体描述
@ApiIgnore：使用该注解忽略这个API
@ApiError ：发生错误返回的信息
@ApiImplicitParam：一个请求参数
@ApiImplicitParams：多个请求参数
整篇文章就到此结束，如果大家在整合的过程中还有什么问题可以留言给我，我也把我自己整合的源码放到github上，大家可以点击阅读原文来clone，下方也留了github的链接，也别忘记给我star哦。
github仓库链接：https://github.com/wuyanzu01/springboot2swagger2
请关注微信公众号：请快点喜欢我
网友评论