一.swagger是什么?
1、是一款让你更好的书写API文档的规范且完整框架。
2、提供描述、生产、消费和可视化RESTful Web Service。
3、是由庞大工具集合支撑的形式化规范。这个集合涵盖了从终端用户接口、底层代码库到商业API管理的方方面面。
二.与springBoot整合
1.在pom.xml 文件中添加依赖
<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>
2.注入配置
@Configuration
@EnableSwagger2
public class SaggerConfig {
@Bean
public Docket createRestApi () {
return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select()
//使用注解
.apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
//包
//.apis(RequestHandlerSelectors.basePackage("com.qzt360"))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo () {
return new ApiInfoBuilder()
//标题
.title("awifi备案平台RESTful APIs")
//描述
.description("awifi备案平台RESTful APIs")
//创建人
.contact(new Contact("luowuhui","",XXXXX.com"))
//版本
.version("1.0").build();
}
}
说明:
ApiInfo:api文档的基本信息
Docket:配置框架的工作方式
apiInfo():配置基本说明信息
apis(): 配置api选择方式(包,类注解,方法注解)
paths():配置扫描路径(所有,正则匹配)
3.定义api文档实例
@RestController
@Api(tags = "这个类的标签")
@ApiRes
@RequestMapping(value = "/test", method = RequestMethod.GET)
public class TestController {
@ApiOperation(value = "描述接口作用", notes = "对接口的额外说明", response = String.class)
@ApiImplicitParam(name = "te", value = "解析该参数作用..", required = true, dataType = "String", paramType = "path")
@RequestMapping(value = "/test")
public String test (String te) {
return "tets";
}
}
4.效果
5.注解说明
@ApiOperation：用在请求的方法上，说明方法的用途、作用
value=“说明方法的用途、作用”
notes=“方法的备注说明”
@ApiImplicitParam ：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面
name：参数名
value：参数的汉字说明、解释
required：参数是否必须传
paramType：参数放在哪个地方
· header --> 请求参数的获取：@RequestHeader
· query --> 请求参数的获取：@RequestParam
· path（用于restful接口）–> 请求参数的获取：@PathVariable
· body（不常用）
· form（不常用）
dataType：参数类型，默认String，其它值dataType=“Integer”
defaultValue：参数的默认值