为什么使用Swagger2
1.由于接口众多,并且细节复杂(需要考虑不同的HTTP请求类型、HTTP头部信息、HTTP请求内容等),高质量地创建这份文档本身就是件非常吃力的事,下游的抱怨声不绝于耳。
2.随着时间推移,不断修改接口实现的时候都必须同步修改接口文档,而文档与代码又处于两个不同的媒介,除非有严格的管理机制,不然很容易导致不一致现象。
Swagger2相关依赖依赖
<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>
swagger基本配置
@Configuration注解代表上图SwaggerConfig类为配置类,启动boot后自动加载到容器中。
@EnableSwagger2则是用来启动Swagger支持,表示这是一个Spring Swagger的配置文件。
定义了一个Bean方法CustomDocket,Spring中名字并不重要,重要的是它返回一个Docket类,DocumentationType.SWAGGER_2作为Docket构造方法的参数,指定了所用的swagger版本2.0,而之后的apiInfo则是调用接下来的apiInfo函数,来创建Docket的信息。apiInfo函数采用ApiInfoBuilder类的build方法来创建ApiInfo类,build方法中所加入的参数将显示在swagger生成的Api接口文档中。
![](https://img2018.cnblogs.com/blog/1752357/201908/1752357-20190824152459298-310806043.png)
配置swagger-ui依赖中的Swagger2-Api文档页面的访问权限,重写WebMvcConfigurer类中的addResourceHandlers方法,允许指定资源访问,配置完成后即可访问生成的Api文档
swagger界面
![](https://img2018.cnblogs.com/blog/1752357/201908/1752357-20190824152601987-794695579.png)
登录之后界面如下:
![](https://img2018.cnblogs.com/blog/1752357/201908/1752357-20190824152719456-386163828.png)
swagger注解的使用
@Api:一般用于Controller中,用于接口分组。(如:@Api(value = "用户接口", description = "用户接口", tags = {"1.1.0"})
@ApiOperation:接口说明,用于controller控制层方法上。(如: @ApiOperation(value = "用户查询", notes = "根据ID查询用户信息"))
@ApiParam:接口说明,用于controller控制层方法参数上。(如: @ApiParam(name=“userId”,value = “用户ID", notes = "根据ID查询用户信息"))
@ApiModelProperty:实体参数说明,这里我通过Mybatis-generate逆向工程生成了swagger注解
效果演示:
![](https://img2018.cnblogs.com/blog/1752357/201908/1752357-20190824153027780-1590492930.png)
测试结果成功了,返回了预期想要的参数,以上为spring boot结合swagger插件生成的API接口文档。