Swagger
学习目标：
- 了解Swagger的作用和概念
- 了解前后端分离
- 在SpringBoot中集成Swagger
Swagger简介
前后端分离（主流）
Vue + SpringBoot
后端时代：前端只用管理静态页面；html==>后端。模板引擎==>JSP,后端是主力
前后端分离时代：
- 后端：后端控制层(controller)，服务层(service)，数据访问层(dao)【后端团队】
- 前端：模型层(model)，前端控制层（view-model），视图层(view)【前端团队】
- 伪造后端数据（通过过json模拟）,不需要后端传递，前端可以模拟运行
- 前后端如何交互？ 通过API
- 前后端相对独立，松耦合；
- 前后端甚至可以部署在不同的服务器上
产生一个问题:
- 前后端集成联调，前端人员和后端人员无法做到”即使协商，尽早解决“，最终导致问题集中爆发
解决方案：
- 首先指定schema[计划的提纲],实时更新最新API，降低集成的风险
- 早先年：制定Word计划档案；
- 前后端分离：
- 前端测试后端接口:postman
- 后端提供接口，需要实时更新最新的消息及改动
Swagger
- 号称世界上最流行的Api框架
- RestFul API 文档在线自动生成工具（API文档与API定义同步更新）
- 直接运行，可以在线测试API接口
- 支持多种语言：Java、PHP。。。
官网：https://swagger.io/
在项目使用Swagger需要Springbox
-
swagger
<dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.9.2</version> </dependency> -
ui
<dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.9.2</version> </dependency>
SpringBoot集成Swagger
-
新建一个SpringBoot web项目
-
导入相关依赖（swagger2、ui）
-
新建一个HelloController测试工程是否正确
-
配置Swagger,新建一个config目录，在目录中编写SwaggerConfig文件。
@Configuration @EnableSwagger2 public class SwaggerConfig {}
++ps.目前Swagger已经可以运行，以后的一些Swagger配置就写在这里。++
- 测试运行:http://localhost:8080/swagger-ui.html
配置Swagger信息
Swagger的bean实例Docket
//配置swagger信息apiInfo
private ApiInfo apiInfo(){
//作者信息
Contact contact = new Contact("倪先森", "这里是url", "这里是邮箱");
return new ApiInfo(
"nxs的Swagger的API文档",
"即使再小的帆也能远航",
"1.0",
"urn:tos",
contact,
"Apache 2.0",
"http://www.apache.org/licenses/LICENSE-2.0",
new ArrayList());
}
Swagger配置扫描接口
Docket.select()
@Bean
public Docket docket(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("club.nxs.swagger.controller"))
//RequestHandlerSelectors配置要扫描的方式
//.basePackage() 指定要扫描的包
//.any() 扫描全部
//.none() 全部都不扫描
//withClassAnnotation: 扫描类上的注解,参数是注解的反射对象（ResController.class）
//withMethodAnnotation: 扫描方法上的注解(RequestMapping.class)
//.paths(PathSelectors.ant("/nxs/**"))
//paths():过滤什么路径
.build();
}
如何让Swagger在生产环境中使用，在发布的时候不适用?
- 判断是不是生产环境 flag = false
- 注入enable（flag）
@Bean
public Docket docket(Environment environment){
//设置要显示的Swagger环境
Profiles profile = Profiles.of("dev","test");
//environment.acceptsProfiles 判断是否处在自己设定的环境中
boolean flag = environment.acceptsProfiles(profile);
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.enable(flag) //默认true,是否启用Swagger， 如果是false，Swagger则不会再浏览器显示
.select()
.apis(RequestHandlerSelectors.basePackage("club.nxs.swagger.controller"))
//.paths(PathSelectors.ant("/nxs/**"))
.build();
}
配置文档的分组
.groupName("nxs")
ps:如何配置多个分组? 多个Docket实例即可
@Bean
public Docket docket1(Environment environment){
return new Docket(DocumentationType.SWAGGER_2).groupName("A");
}
@Bean
public Docket docket2(Environment environment){
return new Docket(DocumentationType.SWAGGER_2).groupName("B");
}
@Bean
public Docket docket3(Environment environment){
return new Docket(DocumentationType.SWAGGER_2).groupName("C");
}
实体类配置:
//只要我们的接口中，返回值存在实体类，它就会被扫描到Swagger
@ApiModel("用户实体类") //就是给生成文档加上注释 == @Api("注释")
public class User{
@ApiModelProperty("用户名")
public String username;
}
.................................................
@ResController
public class HelloController{
@ApiOperation("Hello")
@PostMapping(value="/user")
public User user(){
return new User();
}
public class hello2(@ApiParam("用户名") String username){
return "hello";
}
}
总结
- 我们可以通过Swagger给一些比较难理解的属性或者接口，增加注释信息
- 接口文档实时更新
- 可以在线测试
【注意点】在正式发布的时候，关闭Swagger!!!,出于安全考虑，而且节省内存