5 Swagger介绍以及集成
目录
1 Swagger 简介与搭建环境
2 配置Swagger 信息
3 配置扫描接口以及开关
4 分组和接口注释以及小结
1 Swagger 简介
1 由来
前后端分离时代
1 **后端为主的时代,**前端只需要写静态页面,后台要写模板,通过模板引擎加载渲染数据,前端需要通过后端传递数据项目才能运行起
2 前后端分离
- 后端: 后端控制层,服务层,数据访问层 【后端】
- 前端,视图层,前端控制层,
- 伪造后端JSON数据,不需要后端,前端的工程也能运行,
- 前后端交互,通过API
- 前端后独立-松耦合
问题
- 前后端集成联调,前端和后端人员无法做到即使协商
解决
- 指定 schema 计划提纲,实时更新最新的API降低集成的风险
- 早些年,通过Word计划文档,+GIT
2 搭建Swagger 环境
1 编写一个SpringBoot 的HelloWorld程序
2 导入Swagger依赖 注意3.0 版本有较大改动,这里为2.9 版本
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<!-- 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>
3 编写一个配置类-SwaggerConfig来配置 Swagger
@Configuration //配置类
@EnableSwagger2// 开启Swagger2的自动配置
public class SwaggerConfig {
}
4 访问测试 :http://localhost:8080/swagger-ui.html ,可以看到swagger的界面;
2 配置Swagger 的信息
1 Swagger实例Bean是Docket,所以通过配置Docket实例来配置Swaggger。
@Bean //配置docket以配置Swagger具体参数
public Docket docket() {
return new Docket(DocumentationType.SWAGGER_2);
}
2、可以通过apiInfo()属性配置文档信息
@Bean
public Docket getDocket1(){
return new Docket(DocumentationType.SWAGGER_2)
.groupName("A")
.apiInfo(apiInfo())
;
}
@
public ApiInfo apiInfo(){
//作者信息
Contact contact = new Contact("jian", "www.baidu.com", "1222434@qq.com");
return new ApiInfo("狂神的swagger", "配置Swagger的信息", "1.0", "urn:tos",
contact, "Apache 2.0", "http://www.apache.org/licenses/LICENSE-2.0", new ArrayList<VendorExtension>());
}
这里还可以使用ApiInfoBuilder().build来初始化apiInfo
public ApiInfo apiInfo(){
return new ApiInfoBuilder().title("老罗的Swagger")
.version("初始版本 1.0")
.contact(new Contact("老罗","www.baidu.com","cup_1sdf2078935@163.com"))
.description("springboot swagger 学习").build();
}
3 访问测试 http://localhost:8080/swagger-ui.html
3 配置扫描接口以及开关
1 构建Docket时通过select()方法配置怎么扫描接口。
@Bean
public Docket docket() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()// 通过.select()方法,去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
.apis(RequestHandlerSelectors.basePackage("com.swagger.controller"))
.build();
}
.select() 返回的是一个 ApiSelectorBuilder 对象
ApiSelectorBuilder 有三个方法
- build() //返回一个Docket实例
- apis() //配置要扫描的接口
- paths() //配置扫描过滤
public Docket build() //返回一个Docket实例
public ApiSelectorBuilder paths(Predicate<String> selector) //配置扫描过滤
public ApiSelectorBuilder apis(Predicate<RequestHandler> selector) //配置要扫描的接口
通常配置要扫描的接口,可以通过RequestHandlerSelectors的静态方法
public static Predicate<RequestHandler> any() // 扫描所有接口
public static Predicate<RequestHandler> none() // 不扫描接口
public static Predicate<RequestHandler> withMethodAnnotation // public static Predicate<RequestHandler> withMethodAnnotation //扫描方法上Xxx注释的接口
public static Predicate<RequestHandler> withClassAnnotation //扫描类上有Xxx注释的接口
public static Predicate<RequestHandler> basePackage//扫描哪些包
通常配置要过滤的接口,可以通过类PathSelectors的静态方法
//过滤所有的
public static Predicate<String> any() {
return Predicates.alwaysTrue();
}
//什么都不过滤
public static Predicate<String> none() {
return Predicates.alwaysFalse();
}
//过滤符合正则表达式的路径
public static Predicate<String> regex(final String pathRegex) {
return new Predicate<String>() {
public boolean apply(String input) {
return input.matches(pathRegex);
}
};
}
//过滤指定的路径
public static Predicate<String> ant(final String antPattern) {
return new Predicate<String>() {
public boolean apply(String input) {
AntPathMatcher matcher = new AntPathMatcher();
return matcher.match(antPattern, input);
}
};
}
例子
@Bean
public Docket docket() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()// 通过.select()方法,去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
.apis(RequestHandlerSelectors.basePackage("com.kuang.swagger.controller"))
// 配置如何通过path过滤,即这里只扫描请求以/kuang开头的接口
.paths(PathSelectors.ant("/swagger/**"))
.build();
}
2 配置开关
1、通过enable()方法配置是否启用swagger,如果是false,swagger将不能在浏览器中访问了
@Bean
public Docket docket() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.enable(false) //配置是否启用Swagger,如果是false,在浏览器将无法访问
.select()// 通过.select()方法,去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
.apis(RequestHandlerSelectors.basePackage("com.kuang.swagger.controller"))
// 配置如何通过path过滤,即这里只扫描请求以/kuang开头的接口
.paths(PathSelectors.ant("/kuang/**"))
.build();
}
2 问题如何配置当项目处于test、dev环境时显示swagger,处于prod时不显示?
- 检查test、dev环境 是否激活,激活则为true
@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)
.apiInfo(apiInfo())
.enable(b) //配置是否启用Swagger,如果是false,在浏览器将无法访问
.select()// 通过.select()方法,去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
.apis(RequestHandlerSelectors.basePackage("com.kuang.swagger.controller"))
// 配置如何通过path过滤,即这里只扫描请求以/kuang开头的接口
.paths(PathSelectors.ant("/kuang/**"))
.build();
}
- Profiles.of(“dev”, “test”); 获取要检测 的环境
- environment.acceptsProfiles(of); 判断环境是否激活
设置多文档环境
server:
port: 8080
spring:
profiles:
active: prod
---
spring:
profiles: dev
server:
port: 8081
---
spring:
profiles: prod
server:
port: 8082
3 测试,成功
4 分组和接口注释以及小结
1 如果没有配置分组,默认是default。通过groupName()方法即可配置分组:
@Bean
public Docket docket(Environment environment) {
return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
.groupName("hello") // 配置分组
// 省略配置....
}
2 重启项目查看分组
3、如何配置多个分组?配置多个分组只需要配置多个docket即可:
@Bean
public Docket docket1(){
return new Docket(DocumentationType.SWAGGER_2).groupName("group1");
}
@Bean
public Docket docket2(){
return new Docket(DocumentationType.SWAGGER_2).groupName("group2");
}
@Bean
public Docket docket3(){
return new Docket(DocumentationType.SWAGGER_2).groupName("group3");
}
结果
Model 测试
可以发现Model 并没有内容,
1 建立一个实体类
@ApiModel("用户实体")
public class User {
@ApiModelProperty("用户名")
public String username;
@ApiModelProperty("密码")
public String password;
}
2 只要这个实体在请求接口的返回值上(即使是泛型),都能映射到Model项中:
@RequestMapping("/getUser")
public User getUser(){
return new User();
}
并不是因为@ApiModel这个注解让实体显示在这里了,而是只要出现在接口方法的返回值上的实体都会显示在这里,而@ApiModel和@ApiModelProperty这两个注解只是为实体添加注释的。
@ApiModel为类添加注释
@ApiModelProperty为类属性添加注释
3 接口注释
Swagger的所有注解定义在io.swagger.annotations包下
下面列一些经常用到的,未列举出来的可以另行查阅说明:
- 描述方法的注解
- @ApiOperation(value = “请求swagger方法”,notes =“这是一个hello方法”)
- 描述参数的注解
- 单个参数
- @ApiImplicitParam 作用在方法上,描述一个参数
- 多个参数
- @ApiImplicitParams({
@ApiImplicitParam(name = “username”,value = “用户名”),
@ApiImplicitParam(name = “pwd”,value = “密码”)
})
这样的话,可以给一些比较难理解的属性或者接口,增加一些配置信息,让人更容易阅读!
,提醒下大家在正式环境要记得关闭Swagger,一来出于安全考虑二来也可以节省运行时内存。
@RequestParam:将请求参数绑定到你控制器的方法参数上(是springmvc中接收普通参数的注解)
总结
Swagger 的使用步骤
- 1 导入swagger依赖
- 2 配置Swagger
- 1 配置Docket
- 2 配置apiInfo
- 3 在扫描的接口上配置注释信息