今天我们讲一讲Swagger这个框架。
一、准备工作
首先说说POM文件里面需要加什么依赖
<!-- Swagger -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.6.1</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.6.1</version>
</dependency>
以上为Swagger需要的依赖
接下来需要一个Swagger配置类
Swagger配置类
以下为配置类代码
@Configuration
@ComponentScan(basePackages = { "com.test.controller" })//配置controller路径
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.test"))//扫描com路径下的api文档
.paths(PathSelectors.any())//路径判断,这里是任何路径
.build();
}
private ApiInfo apiInfo() {
return new ApiInfo("测试接口-JAVA版",//大标题
"测试",//小标题
"1.0",//版本
"001",
"老虎",//作者
"官方网址",//链接显示文字
"www.baidu.com"//网站链接
);
}
}
apiInfo
apiInfo中有一些，作者也没弄明白的，其实是懒得看了。如果大家知道，请在博客下方留言，谢谢。
到这儿就算是准备工作完成了，接下来介绍一下Swagger的注解。注解，我只会讲比较常用的。就是开发过程中用到的，那些太偏门的，就留着有空慢慢研究吧。
二、Swagger注解
先来看个截图，根据截图我们讲解一下注解
注解
2.1@ApiModel
该注解用于描述Model类
主要使用：
value: 类的说明
reference: 这个本人也没搞明白做啥的,有明白的请在博客留言啊 ~~~~(>_<)~~~~
2.2@ApiModelProperty
该注解主要用于字段属性。如果跟用于Controller的注解结合使用，就会有意向不到的效果
主要使用：
value: 字段说明
dataType: 字段类型描述（String、Integer之类的）
required: 是否为空;不用的时候,不写默认为false
example:字段示例值,用于Swagger文档页面展示使用
以上两个注解主要是用于Model类的。在Swagger页面上显示如图
image.png
image.png
有没有发现一个问题，第一张图跟第二张图少了许多。
没错，就是接下来我们要讲的用于Controller的注解。
Controller代码
@RestController
@RequestMapping("test")
@Api(value = "测试", description = "测试Controller", tags = "test")
public class TestController {
@ApiOperation(value="获取用户列表", notes="获取用户列表", httpMethod = "POST",
response = TestUser.class, produces = "application/json")
@RequestMapping("getUserList")
public List<TestUser> getUserList(@RequestBody @ApiParam TestUser tu) {
List<TestUser> r = new ArrayList<TestUser>();
return r;
}
}
2.3@Api
value:用于描述Controller,与tags相冲
tags:用于归纳Controller,与value相冲
value跟tags这俩,如果有了tags的话,value则无效,否则value有效。
description: Controller的描述
如图
image.png
2.4@ApiOperation
主要用于修饰Controller类的方法
value: 方法描述
notes: 方法进一步详细描述
response: 方法返回值必须是 xxx.class
produces: 方法返回类型 基本是application/json
如图
image.png
双击红框处，红框的内容会到椭圆形的位置去。点击左下角的try it out即可发起请求进行测试。
