本文介绍了Swagger在前后端分离的背景下，作为API接口管理和测试工具的重要作用。详细阐述了如何在SpringBoot项目中集成Swagger，包括配置Swagger、定义扫描接口、设置文档分组以及实体类的配置。同时，强调了Swagger的注解使用，如@ApiModel和@ApiOperation，以增强接口的可读性和测试性。最后，提醒在项目正式发布时要关闭Swagger，确保安全性。
1、swagger配置，将Docket对象注入到容器中
2、通过对Docket对象设置属性，配置swagger文档
3、可配置swagger的info、接口扫描方式、该环境是否启动（判断environment）、api文档分组等功能
4、注解：
@EnableSwagger2 swagger配置类上， 开启swagger
@ApiOperation 在接口方法上配置
@ApiModel 实体类注解
@ApiModelProperty 实体类属性注解
Swagger
学习目标：
- 了解Swagger的作用和概念
- 了解前后端分离
- 在springboot中集成Swagger
Swagger简介：
前后端分离
Vue+SpringBoot
后端时代：前端只用管理静态页面；模板引擎JSP =》后端主力
前后端分离：
- 后端：后端控制层，服务层，数据访问层
- 前端：前端控制层，视图层
- 前端伪造后端Json，数据已经存在了，不需要后端，前端工程也能跑起来
- 前后端如何交互？=》API接口
- 前后端相对独立，松耦合
- 前后端甚至可以部署在不同的服务器上
前后端产生一个问题：前后端集成联调，无法做到“即时协商，协调解决”，导致问题集中爆发。
解决方案：制定schema[计划]，实时更新API,降低集成风险
Swagger
- 号称世界上最流程的 Api 框架
- Restful 风格Api文档在线自动生成工具==》Api定义与文档同步更新
- 直接运行，在线测试Api接口
-支持多种语言【java、php】
SpringBoot集成Swagger
1、集成swagger
- 新建springboot的web项目,导入Swagger依赖包
<!--3.0.0版本需要导入springfox-boot-starter依赖才能打开swagger的ui页面-->
<!--推荐使用2.9.2版本，3.0.0版本配置自定义Docket会有问题-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
- 编写Swagger配置类,注解 @EnableSwagger2 开启Swagger
@Configuration
@EnableSwagger2 //开启Swagger
public class SwaggerConfig {
}
- 访问 http://localhost:8081/swagger-ui.html
2、配置swagger
Swagger的bean实例Docket；
//配置了swagger的 Docket的 bean实例
@Bean
public Docket docket(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo());W//设置接口信息及作者信息W
}
//配置Swagger信息ApiInfo
public ApiInfo apiInfo(){
//作者信息
Contact contact = new Contact("王罕的Contact", "http://www.by2253.com", "592844440@qq.com");
return new ApiInfo(
"王罕的swagger",
"再小的帆也能远航",
"1.0",
"http://www.by2253.com",
contact,
"Apache 2.0",
"http://www.apache.org/licenses/LICENSE-2.0",
new ArrayList()
);
}
3、swagger配置扫描接口
Docket.select()方法
@Bean
public Docket docket(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())//设置接口信息及作者信息
.select()
//RequestHandlerSelectors配置要扫描接口的方式
//any())//扫描全部
//none())//不扫描
//withClassAnnotation(Controller.class))//基于类注解扫描
//withMethodAnnotation(GetMapping.class))//基于方法注解扫描
.apis(RequestHandlerSelectors.basePackage("com.kuang.swagger.controller")) //基于包
//过滤器 只扫描请求路径带/kuang的接口
.paths(PathSelectors.ant("/kuang/**"))
.build();
}
//配置Swagger信息ApiInfo
public ApiInfo apiInfo(){
//作者信息
Contact contact = new Contact("王罕的Contact", "http://www.by2253.com", "592844440@qq.com");
return new ApiInfo(
"王罕的swagger",
"再小的帆也能远航",
"1.0",
"http://www.by2253.com",
contact,
"Apache 2.0",
"http://www.apache.org/licenses/LICENSE-2.0",
new ArrayList()
);
}
4、配置是否启动swagger
Docket中的enable()方法是默认开启的，如果有多个Docket，需要同时设置enable(false)才能关闭
Swagger；
如果想要设置在指定的开发环境才启用Swagger，可以传入Environment 对象，通过该对象中传入
的启用环境名称，取判断获取到的开发环境是否是与启动Swagger的环境一致，如果不一致，则将
返回值flag传入Docket的enable()方法中，则设置swagger不启动
//配置了swagger的 Docket的 bean实例
@Bean
public Docket docket(Environment environment){
//设置启用swagger的开发环境
Profiles profiles = Profiles.of("dev","test");
//获取开发环境，如果是dev或test环境则返回值为true
boolean flag = environment.acceptsProfiles(profiles);
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())//设置接口信息及作者信息
.enable(flag)//是否启用swagger ，如果为false，则不能在浏览器中访问swagger
.select()
//RequestHandlerSelectors配置要扫描接口的方式
//any())//扫描全部
//none())//不扫描
//withClassAnnotation(Controller.class))//基于类注解扫描
//withMethodAnnotation(GetMapping.class))//基于方法注解扫描
.apis(RequestHandlerSelectors.basePackage("com.kuang.swagger.controller")) //基于包
//过滤器 只扫描请求路径带/kuang的接口
.paths(PathSelectors.ant("/kuang/**"))
.build();
}
//配置Swagger信息ApiInfo
public ApiInfo apiInfo(){
//作者信息
Contact contact = new Contact("王罕的Contact", "http://www.by2253.com", "592844440@qq.com");
return new ApiInfo(
"王罕的swagger",
"再小的帆也能远航",
"1.0",
"http://www.by2253.com",
contact,
"Apache 2.0",
"http://www.apache.org/licenses/LICENSE-2.0",
new ArrayList()
);
}
5、配置Api文档的分组
实质就是多添加几个Docket类，不同的类，配置不同的groupName和不同的扫描路径或方式
//配置多个Docket，实现分组
@Bean
public Docket docketA() {
return new Docket(DocumentationType.SWAGGER_2).groupName("A").select().paths(PathSelectors.ant("/A/**")).build();
}
@Bean
public Docket docketB() {
return new Docket(DocumentationType.SWAGGER_2).groupName("B").select().paths(PathSelectors.ant("/B/**")).build();
}
@Bean
public Docket docketC() {
return new Docket(DocumentationType.SWAGGER_2).groupName("C").select().paths(PathSelectors.ant("/C/**")).build();
}
//配置了swagger的 Docket的 bean实例
@Bean
public Docket docket(Environment environment){
//设置启用swagger的开发环境
Profiles profiles = Profiles.of("dev","test");
//获取开发环境，如果是dev或test环境则返回值为true
boolean flag = environment.acceptsProfiles(profiles);
System.out.println(flag);
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())//设置接口信息及作者信息
.enable(flag)//是否启用swagger ，如果为false，则不能在浏览器中访问swagger
.groupName("wanghan")
.select()
//RequestHandlerSelectors配置要扫描接口的方式
//.apis(RequestHandlerSelectors.any())//扫描全部
//.apis(RequestHandlerSelectors.none())//不扫描
//.apis(RequestHandlerSelectors.withClassAnnotation(Controller.class))//基于类注解扫描
//.apis(RequestHandlerSelectors.withMethodAnnotation(GetMapping.class))//基于方法注解扫描
.apis(RequestHandlerSelectors.basePackage("com.kuang.swagger.controller")) //基于包
//过滤器 只扫描请求路径带/kuang的接口
.paths(PathSelectors.ant("/kuang/**"))
.build();
}
//配置Swagger信息ApiInfo
public ApiInfo apiInfo(){
//作者信息
Contact contact = new Contact("王罕的Contact", "http://www.by2253.com", "592844440@qq.com");
return new ApiInfo(
"王罕的swagger",
"再小的帆也能远航",
"1.0",
"http://www.by2253.com",
contact,
"Apache 2.0",
"http://www.apache.org/licenses/LICENSE-2.0",
new ArrayList()
);
}
6、实体类配置
实体类的配置，只需要在API接口中返回值用到实体类，则实体类就会被Swagger扫描到
@ApiOperation("用户控制器")
@RequestMapping("/kuang/user")
//只要在我们的接口中，返回值类型存在实体类，则这个实体类就会被swagger扫描到
public User user(@ApiParam("用户名") String username){
return new User();
}
Swagger的注解：
实体类 : @ApiModel(“用户实体类”) @ApiModelProperty(“用户ID”)
@ApiModel("用户实体类")
public class User {
@ApiModelProperty("用户ID")
private int id;
@ApiModelProperty("用户名")
private String name;
@ApiModelProperty("密码")
private String pwd;
}
Controller :@ApiOperation(“获取用户controller”) @ApiParam(“用户名”)
@ApiOperation("获取用户controller")
@RequestMapping("/kuang/user")
//只要在我们的接口中，返回值类型存在实体类，则这个实体类就会被swagger扫描到
public User user(@ApiParam("用户名") String username){
return new User();
}
总结：
- 可以通过给一些难理解的接口或属性，增加注释
- 接口文档实时更新
- 可以在线测试
【注意点】：在正式发布的时候，关闭Swagger！！！出于安全考虑，而且节省运行的内存
扫一扫
2274
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
