Swagger简介
- 前后端分离的产物
- 用于协调前后端的问题,发现问题能及时解决,免得问题集中爆发
- 好处(百度):
1:号称世界上最流行的API框架
2:Restful Api 文档在线自动生成器 => API 文档 与API 定义同步更新
3:直接运行,在线测试API
4:支持多种语言 (如:Java,PHP等) - 官网:https://swagger.io/
springboot集成swagger
注意点
使用Swagger
要求:jdk 1.8 + 否则swagger2无法运行
使用springboot-web项目进行测试
依赖
swagger-ui和swagger2
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
配置类
Swagger
@Configurtion
public class SwaggerConfig {}
在主类上开启注解支持
@EnableSwagger2
测试运行
测试网站:http://localhost:8080/swagger-ui.html
结果:
Swagger配置
1:更改默认信息
在SwaggerConfig配置类中进行配置
@Bean
public Docket docket(){
return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());
}
public ApiInfo apiInfo(){
//作者信息
Contact contact = new Contact("庄忠旺", "链接url", "1935912115@qq.com");
return new ApiInfo(
"旺桑", //题目
"每日一问:李汀加你了吗", //描述
"1", //版本号
"urn:tos", //链接
contact, //作者信息
"Apache 2.0", //开源版本号
"http://www.apache.org/licenses/LICENSE-2.0",
new ArrayList()
);
}
2 配置扫描接口
1 构建Docket时通过select()方法配置怎么扫描接口。
@Bean
public Docket docket(){
return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
.select()
// 通过.select()方法,去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
// any() 扫描所有,项目中的所有接口都会被扫描到
// none() 不扫描接口
// 通过方法上的注解扫描,如withMethodAnnotation(GetMapping.class)只扫描get请求
// withMethodAnnotation(final Class<? extends Annotation> annotation)
// 通过类上的注解扫描,如.withClassAnnotation(Controller.class)只扫描有controller注解的类中的接口
// withClassAnnotation(final Class<? extends Annotation> annotation)
// basePackage(final String basePackage)根据包路径扫描接口
.apis(RequestHandlerSelectors.basePackage("com.sun.config.hello"))
// 配置如何通过path过滤,即这里只扫描请求以/h开头的接口
.paths(PathSelectors.ant("/h/**"))
.build();
}
2:过滤接口
这里是扫描com.sun.controller这个包,然后只扫描请求以/a1开头的接口
@Bean
public Docket docket(Environment environment){
return new Docket(DocumentationType.SWAGGER_2)
.groupName("d")
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.sun.controller"))
// 配置如何通过path过滤,即这里只扫描请求以/a1开头的接口
.paths(PathSelectors.ant("/h3/**"))
.build();
}
结果:
配置Swagger开关
如何动态配置当项目处于test、dev环境时显示swagger,处于prod时不显示?
@Bean
public Docket docket(Environment environment){
// 设置要显示swagger的环境
Profiles of = Profiles.of("dev","test");
// 判断当前是否处于该环境
// 通过 enable() 接收此参数判断是否要显示
boolean b = environment.acceptsProfiles(of);
return new Docket(DocumentationType.SWAGGER_2)
.groupName("d")
.apiInfo(apiInfo())
// 如果为false,就不使用swagger
.enable(b)
.select()
.apis(RequestHandlerSelectors.basePackage("com.sun.controller"))
// 配置如何通过path过滤,即这里只扫描请求以/a1开头的接口
// .paths(PathSelectors.ant("/h3/**"))
.build();
}
这里不做配置,用默认的环境进行测试,如果不是**“dev”,“test”**环境,就会访问不到
配置实体类
pijo
public class User {
public String name;
public String pwd;
}
controller
返回一个User对象和Swagger进行关联
@GetMapping("/a1")
public User h2(){
return new User();
}
进行测试
API分组
在配置类中简单配置
@Bean
public Docket docket1(){
return new Docket(DocumentationType.SWAGGER_2).groupName("a");
}
@Bean
public Docket docket2(){
return new Docket(DocumentationType.SWAGGER_2).groupName("b");
}
@Bean
public Docket docket3(){
return new Docket(DocumentationType.SWAGGER_2).groupName("c");
}
@Bean
public Docket docket(){
return new Docket(DocumentationType.SWAGGER_2).groupName("d");
}
配置成功之后有4个分组
API注释(生成文档)
实体类注释
pojo
@ApiModel("用户实体类") //中文注释,放在类上,说明这是一个用户实体类
public class User {
@ApiModelProperty("姓名") //中文注释,放在属性上,说明这是一个这是一个什么参数
public String name;
@ApiModelProperty("密码")
public String pwd;
}
结果:
接口注释
@ApiOperation("h3控制类") //中文注释,放在类上,说明这是h3的控制类类
@GetMapping("/h3")
public String h3(@ApiParam("用户名") String name){ //@ApiParam("用户名") 中文注释,放在参数前面,说明传的这个传输为用户名
return "hello"+name;
}
结果
Swagger测试(最重要的功能)
测试get
测试代码
@GetMapping("/h1")
public String h1(){
return "hello";
}
无参请求:
1:每一个请求都有一个try it out 点击就可以进行测试了
这里以a1为例,由于没有参数,所以直接请求了,200代表成功
get请求
测试代码:
注意:这里ApiImplicitParam里面的name=参数 要和方法定义的一致
@ApiImplicitParams(
@ApiImplicitParam(name="username",required=true,dataType="String",paramType="query")
)
@ApiOperation("h3控制类") //中文注释,放在类上,说明这是h3的控制类类
@GetMapping("/h3")
public String h3(@ApiParam("用户名") String username){ //@ApiParam("用户名") 中文注释,放在参数前面,说明传的这个传输为用户名
return "hello"+username;
}
结果
Post请求
测试代码
@ApiOperation("post测试类") //中文注释,放在类上,说明这是h3的控制类类
@PostMapping("/post")
public User Post(@ApiParam("用户") User user){ //@ApiParam("用户") 中文注释,放在参数前面,说明传的这个传输为用户名
return user;
}
结果