swagger简介:
Swagger是一款RESTFUL接口的文档在线自动生成+功能测试功能软件。Swagger是一个规范和完整的框架,用于生成、描述、调用和可视化RESTfu风格的web服务。目标是使客户端和文件系统作为服务器一同样的速度来更新文件的方法,参数和模型紧密集成到服务器。这个解释简单点来讲就是说,swagger是一款可以根据restful风格生成的接口开发文档,并且支持做测试的一款中间软件。
swagger使用:
引入依赖
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
添加配置类:
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket docket(Environment environment){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.enable(true)//关闭swagger,默认是true
.select()
//RequestHandlerSelectors:配置要扫描的方式,有basePackage("路径")、any():扫描全部,none():全部不扫描
//RequestHandlerSelectors.withMethodAnnotation():扫描方法上的注解
//.withClassAnnotation():扫描类上的注解
.apis(RequestHandlerSelectors.basePackage("com.beiyou"))//指定扫描的包
.paths(PathSelectors.ant("/**"))//设置请求路径,这里是带有hello的请求路径
.build() ;
}
private ApiInfo apiInfo(){
// Contact contact = new Contact("suicer", "https://blog.csdn.net", "xxx@qq.com");
return new ApiInfo(
"***的Api",
"请认真查看",
"v2.0",
"https://www.baidu.com",
null,
"Apache 2.0",
"http://www.apache.org/licenses/LICENSE-2.0",
new ArrayList()
);
}
}
访问:
http://localhost:yourport/swagger-ui.html
swagger常用注解
@Api()
用在请求的类上,表示对类的说明,也代表了这个类是swagger2的资源。
参数:
tags:说明该类的作用,参数是个数组,可以填多个。
value=“该参数没什么意义,在UI界面上不显示,所以不用配置”
description = “用户基本信息操作”
@ApiOperation()
用于方法,表示一个http请求访问该方法的操作。
参数:
value=“方法的用途和作用”
notes=“方法的注意事项和备注”
tags:说明该方法的作用,参数是个数组,可以填多个。
格式:tags={“作用1”,“作用2”}
(在这里建议不使用这个参数,会使界面看上去有点乱,前两个常用)
@ApiModel()
用于响应实体类上,用于说明实体作用。
参数:
description=“描述实体的作用”
@ApiModelProperty
用在属性上,描述实体类的属性
参数:
value=“用户名” 描述参数的意义
name=“name” 参数的变量名
required=true 参数是否必选
@ApiImplicitParams
用在请求的方法上,包含多@ApiImplicitParam
@ApiImplicitParam
用于方法,表示单独的请求参数。
参数:
name=“参数ming”
value=“参数说明”
dataType=“数据类型”
paramType=“query” 表示参数放在哪里
-header–>请求参数的获取:@RequestHeader(代码中接收注解) -query–>请求参数的获取:@RequestParam(代码中接收注解)
-path(用于restful接口)–>请求参数的获取:@PathVariable(代码中接收注解)
-body–>请求参数的获取:@RequestBody(代码中接收注解)
-form(不常用,form.serilize())
defaultValue=“参数的默认值”
required=“true” 表示参数是否必须传
@ApiParam()
用于方法,参数,字段说明 表示对参数的要求和说明。
参数:
name=“参数名称”
value=“参数的简要说明”
defaultValue=“参数默认值”
required=“true” 表示属性是否必填,默认为false
@ApiResponses
用于请求的方法上,根据响应码表示不同响应。
一个@ApiResponses包含多个@ApiResponse。
@ApiResponse
用在请求的方法上,表示不同的响应。
参数:
code=“404” 表示响应码(int型),可自定义
message=“状态码对应的响应信息”
@ApiIgnore()
用于类或者方法上,不被显示在页面上。
@Profile({“dev”, “test”})
用于配置类上,表示只对开发和测试环境有用。