Swagger
1. 学习目标
- 了解Swagger的概念和作用
- 了解前后端分离
- 在Springboot中集成Swagger
2. Swagger简介
前后端分离
- 后端：后端控制层、服务层、数据访问层
- 前端：前端控制层、视图层
- 伪造后端数据，json格式。作为测试数据，因此不需要后端前端工程也能跑起来，并且数据对应着数据库的各个表和各个字段。前后端接轨时只需要把从本地获取的这些数据换成从后端提供的接口获取就可以
- 前后端交互：API
- 前后端相对独立，彼此松散耦合，甚至可以部署在不同的服务器上
- 问题：前后端集成联调的协商
- 解决方案
- 首先指定一个schema，实时更新最新的API，降低集成风险
Swagger
- 号称世界上最流行的API框架
- RestFul Api文档在线自动生成工具=>Api文档与Api定义同步更新
- 直接运行，可以在线测试API接口
- 支持多种语言：Java、PHP...
官网：链接
3. Springboot集成Swagger
-
新建一个springboot项目
-
导入两个依赖：springfox-swagger2、springfox-swagger-ui
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 --> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>3.0.0</version> </dependency> <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui --> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>3.0.0</version> </dependency> -
集成Swagger
创建配置类SwaggerConfig，添加注解
@Configuration @EnableSwagger2 //开启swagger2 public class SwaggerConfig { } -
测试运行：http://localhost:8080/swagger-ui.html
启动时报空指针异常：
Failed to start bean 'documentationPluginsBootstrapper'; nested exception is java.lang.NullPointerException如果是swagger3.0.0及更新的版本，由于静态文件位置发生了变化，无法通过上述地址进行访问。需要去掉上述引进的两个依赖，重新引进下面的依赖
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-boot-starter --> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-boot-starter</artifactId> <version>3.0.0</version> </dependency>并在主程序启动类添加注解
@EnableOpenApi之后通过http://localhost:8080/swagger-ui/index.html访问
4. Swagger扫描接口
配置类SwaggerConfig
扫描接口，在Docket的创建时添加下列配置
- .select()
- .apis(RequestHandlerSelectors.) ==> RequestHandlerSelectors用来配置扫描接口的方式
- basePackage("···") ==> 指定要扫描的包
- any() ==> 扫描全部
- none() ==> 不扫描
- withClassAnnotation() ==> 扫描类上的注解，参数是一个注解的反射对象
- withMethodAnnotation() ==> 扫描方法上的注解
- paths(PathSelectors.) ==> 过滤什么路径
配置要显示Swagger的环境
指定环境下才使Swagger可用
//配置要显示Swagger的环境，这里设置了dev和test环境下才开启Swagger
Profiles profiles = Profiles.of("dev","test");
//通过environment.acceptsProfiles判断是否处在自己设定的环境当中
boolean flag = environment.acceptsProfiles(profiles);
Swagger配置类代码
@Configuration
@EnableSwagger2
public class SwaggerConfig {
// 配置基本信息
@Bean
public ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("Rodrigol的Swagger API文档")
.description("仰天大笑出门去，我辈岂是蓬蒿人")
.termsOfServiceUrl("http://47.115.222.44")
.contact(new Contact("Rodrigol","https://blog.csdn.net/Lyao_Boker","[email protected]"))
.version("1.0")
.build();
}
//配置Swagger的Docket的Bean实例
@Bean
public Docket docket(Environment environment) {
//配置要显示Swagger的环境，这里设置了dev和test环境下才开启Swagger
Profiles profiles = Profiles.of("dev","test");
//通过environment.acceptsProfiles判断是否处在自己设定的环境当中
boolean flag = environment.acceptsProfiles(profiles);
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.enable(flag) //enable是否启动Swagger，为False则不能在浏览器中访问Swagger
.select()
.apis(RequestHandlerSelectors.withClassAnnotation(RestController.class))
.paths(PathSelectors.any())
.build();
}
}
5.配置API文档的分组
@Bean
public Docket docket() {
return new Docket(DocumentationType.SWAGGER_2).groupName("A");
}
不同人开发不同的代码，然后各自创建一个自己的docket，扫描自己的对应的包
6. 实体类配置示例
创建实体类User
@ApiModel("用户实体类")
public class User {
@ApiModelProperty("用户名")
public String username;
@ApiModelProperty("密码")
public String password;
}
其中@ApiModel()，@ApiModelProperty()注解相当于Swagger文档上的实体类、实体类属性的注释
创建控制器UserController
@RestController
public class HelloController {
@GetMapping(value = "/hello") //get请求
public String hello() { return "Hello Swagger"; }
@PostMapping(value = "/user") //post请求
public User user() { return new User(); }
@ApiOperation("halo方法") //Api接口功能注释
@GetMapping(value = "/halo")
public String halo(@ApiParam("用户名") String username) { //@ApiParam()用于对参数的注释
return "Halo Swagger" + username;
}
}