swagger简介
前后端分离
Vue+SpringBoot
后端时代：前端只用管理静态页面；html-->后端。模板引擎 jsp-->后端主力
前后端分离时代：
- 后端：后端控制层，服务层，数据访问层【后端团队】
- 前端：前端控制层，视图层【前端团队】
- 伪造后端数据，josn。已经存在了，不需要后端，前端工程依旧能够跑起来
- 前后端如何交互-->API
- 前后端相对独立，松耦合
- 前后端甚至可以部署在不同的服务器上；
产生一个问题：
- 前后端集成联调，前端人员和后端人员无法做到“及时协商，今早解决”，最终导致问题集中爆发
解决方案： - 首先指定schema[计划的提纲]，实时更新最新API，降低集成的风险；
- 早些年：指定word文档
- 前后端分离：
- 前端测试后端接口：postman
- 后端提供接口，需要实时更新最新的消息及改动！
swagger
- 号称世界最流行的API框架；
- RestFul API 文档在线自动生成工具-->API文档与API定义同步更新
- 直接运行，可在线测试API接口
- 支持多种语言：Java、PHP...
官网
在项目中使用Swagger需要springfox； - swagger2
- ui
SpringBoot集成Swagger
- 新建一个SpringBoot-web项目
- 导入相关依赖
<!-- 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>
- 编写一个Hello程序
@Controller
public class HelloController {
@RequestMapping("/hello")
@ResponseBody
public String hello() {
return "Hello";
}
}
- 配置Swagger-->config
@Configuration // 开启自动配置
@EnableSwagger2 // 开启Swagger2
public class SwaggerConfig {
}
- 测试运行
访问：http://localhost:8080/swagger-ui.html
图片.png
配置Swagger信息
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
import java.util.ArrayList;
@Configuration // 自动配置
@EnableSwagger2 // 开启swagger2
public class SwaggerConfig {
// 配置了Swagger的Docket的bean实例
@Bean
public Docket docket() {
return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());
}
// 配置Swagger信息=apiInfo
private ApiInfo apiInfo() {
// 作者信息
Contact contact = new Contact("赵毅梵", "https://www.jianshu.com/u/26ca55d16ca9", "1184546287@QQ.com");
return new ApiInfo("赵毅梵的SwaggerApi文档", "云鱼科技", "1.0", "https://www.jianshu.com/u/26ca55d16ca9", contact, "Apache 2.0", "www.baidu.com", new ArrayList());
}
}
Swagger配置扫描接口
Docket.select();
// 配置了Swagger的Docket的bean实例
@Bean
public Docket docket() {
return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select()
// RequestHandlerSelectors 配置要扫描接口的方式
// basePackage 指定要扫描的包
// any() 扫描全部
// none() 不扫描
// withClassAnnotation 扫描类上的注解，参数是一个注解的反射对象
// withMethodAnnotation 扫描方法上的注解
.apis(RequestHandlerSelectors.basePackage("com.zhao.swagger.controller"))
// paths() 过滤什么路径
.paths(PathSelectors.ant("/zhao/**")).build();
}
配置是否启动Swagger
// 配置了Swagger的Docket的bean实例
@Bean
public Docket docket() {
return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
// enable是否启动Swagger，如果为false，则Swagger不能在浏览中访问
.enable(true).select().apis(RequestHandlerSelectors.basePackage("com.zhao.swagger.controller"))
// .paths(PathSelectors.ant("/zhao/**"))
.build();
}
应用题
我只希望我的Swagger在生产环境中使用，在发布的时候不使用？
- 判断是不是生产环境 flag=false
- 注入enable（flag）
application.properties
spring.profiles.active=pro
application-dev.properties
server.port=8082
application.properties
server.port=8081
SwaggerConfig
// 配置了Swagger的Docket的bean实例
@Bean
public Docket docket(Environment environment) {
// 设置想要显示的Swagger环境
Profiles profiles = Profiles.of("dev", "test");
// 通过environment.acceptsProfiles()判断是否处在自己设定的环境当中
boolean flag = environment.acceptsProfiles(profiles);
return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
// enable是否启动Swagger，如果为false，则Swagger不能在浏览中访问
.enable(flag).select().apis(RequestHandlerSelectors.basePackage("com.zhao.swagger.controller"))
// .paths(PathSelectors.ant("/zhao/**"))
.build();
}
配置API文档的分组
.groupName("...")
如何配置多个分组，多个Docket实例即可
@Bean
public Docket docket1() {
return new Docket(DocumentationType.SWAGGER_2).groupName("赵");
}
@Bean
public Docket docket2() {
return new Docket(DocumentationType.SWAGGER_2).groupName("毅");
}
@Bean
public Docket docket3() {
return new Docket(DocumentationType.SWAGGER_2).groupName("梵");
}
配置实体类
// 给实体类添加注解，相当于给实体类增加注释信息
@ApiModel("用户实体类")
public class User {
// 给字段添加注解，相当于是给字段增加注释信息
@ApiModelProperty("用户id")
public Integer id;
@ApiModelProperty("用户名")
public String Username;
}
实体类
@Controller
public class HelloController {
// 只要接口中返回值中存在实体类，就会被扫描到Swagger中
@PostMapping("user")
public User user() {
return new User();
}
// Operation接口，不是放在类上的，是方法
@ApiOperation("用户名方法")
@GetMapping("hello1")
public String hello1(@ApiParam("用户名") String username) {
return "用户名：" + username;
}
}
方法
总结
- 我们可以通过Swagger给一些比较难理解的属性或者接口，增加注释信息
- 接口文档实时更新
- 可以在线测试
