swagger的初步认识
一、Swagger
- 号称世界上较流行的API框架
- RestFul API 文档在线自动生成工具 -> API文档与API同步更新
- 直接运行,可以在线测试API接口
- 支持多种语言,如:Java、PHP
什么是Swagger?
- Swagger可以说是一种解决前后端分离的机制
- 前端可以使用伪数据或mork进行交互
- 前后端如何实现交互? -> API
- 前后端相对独立,松耦合
- 前后端可以部署在不同的服务器上
Swagger能够解决什么问题?
- 首先如果前端人员与后端人员某个模块的字段不一致,不能进行实时更新?
- 这个时候swagger指定一个schema[计划的大纲],实时更新的API,降低集成的风险
二、实战Swagger
使用SpringBoot集成Swagger
-
新建一个SpringBoot - Web项目
-
导入Swagger相关依赖
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 --> <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>
-
编写一个Hello工程 -> 控制器 Controller-<
package cn.qj.cnmrli.swagger.controller; import org.springframework.web.bind.annotation.RequestMapping; import org.springframework.web.bind.annotation.RestController; /** * @author 青衿 * @Date 2021/2/9 19:00 **/ @RestController public class HelloController { @RequestMapping(value = "/hello") public String hello() { return "hello"; } }
-
编写一个Swagger配置类 -> Config -<
package cn.qj.cnmrli.swagger.config; import org.springframework.context.annotation.Configuration; import springfox.documentation.swagger2.annotations.EnableSwagger2; /** * @author 青衿 * @Date 2021/2/9 19:05 **/ @Configuration //TODO 开始swagger2 @EnableSwagger2 public class SwaggerConfig { }
-
启动测试Swagger
http://localhost:8080/swagger-ui.html#/hello-controller
三、配置Swagger
Swagger的bean实例Docket;
//TODO 配置了Swagger的Docket的bean实例
@Bean
public Docket docket() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo());
}
//TODO 配置Swagger信息 => apiInfo
private ApiInfo apiInfo() {
//TODO 作者信息
Contact contact = new Contact("青衿", "https://blog.csdn.net/", "CnMrLi@163.com");
return new ApiInfo(
"粒桃的SwaggerAPI文档", //标题
"努力的搬运工", //标注
"v1.0", //版本
"https://blog.csdn.net/",//服务地址
contact, //著名、地址、邮箱
"Apache 2.0", //开源版本号
"http://www.apache.org/licenses/LICENSE-2.0",
new ArrayList()
);
}
四、Swagger配置扫描接口
Docket.select()
//TODO 配置了Swagger的Docket的bean实例
@Bean
public Docket docket() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
//TODO RequestHandlerSelectors,配置要扫描接口的方式
//TODO basePackage():指定扫描的包
//TODO any():扫描全部
//TODO none():不扫描
//TODO withClassAnnotation(RestController.class):扫描类上的注解,参数是一个注解的反射对象
//TODO withMethodAnnotation(GetMapping.class):扫描方法上的注解,参数是一个注解的反射对象
.apis(RequestHandlerSelectors.basePackage("cn.qj.cnmrli.swagger.controller"))
//paths():过滤什么路径
.paths(PathSelectors.ant("/qj/**"))
.build();
}
五、配置是否启动Swagger
//TODO 配置了Swagger的Docket的bean实例
@Bean
public Docket docket() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
//TODO enable(false):是否启用Swagger,false为禁用,默认为true启用,则Swagger不能在浏览器中访问
.enable(false)
.select()
//TODO RequestHandlerSelectors,配置要扫描接口的方式
//TODO basePackage():指定扫描的包
//TODO any():扫描全部
//TODO none():不扫描
//TODO withClassAnnotation(RestController.class):扫描类上的注解,参数是一个注解的反射对象
//TODO withMethodAnnotation(GetMapping.class):扫描方法上的注解,参数是一个注解的反射对象
.apis(RequestHandlerSelectors.basePackage("cn.qj.cnmrli.swagger.controller"))
//paths():过滤什么路径
// .paths(PathSelectors.ant("/qj/**"))
.build();
}
六、题外题:
如何保证Swagger在生产中使用,发布后不使用?
- flag=false 判断是不是生产环境
- 注入enable(flag)
//TODO 配置了Swagger的Docket的bean实例
@Bean
public Docket docket(Environment environment) {
//TODO Profiles.of("dev","test"):设置要显示的Swagger的环境
Profiles profiles = Profiles.of("dev", "test");
//TODO 获取项目中的环境如:生产环境、开发环境
//TODO getActiveProfiles():获得一个激活文件
//TODO getDefaultProfiles():获得一个默认文件
//TODO acceptsProfiles():监听一个对象
//environment.acceptsProfiles(profiles):判断是否处在自己设定的环境当中
boolean flag = environment.acceptsProfiles(profiles);
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
//TODO enable(false):是否启用Swagger,false为禁用,默认为true启用,则Swagger不能在浏览器中访问
.enable(flag)
.select()
//TODO RequestHandlerSelectors,配置要扫描接口的方式
//TODO basePackage():指定扫描的包
//TODO any():扫描全部
//TODO none():不扫描
//TODO withClassAnnotation(RestController.class):扫描类上的注解,参数是一个注解的反射对象
//TODO withMethodAnnotation(GetMapping.class):扫描方法上的注解,参数是一个注解的反射对象
.apis(RequestHandlerSelectors.basePackage("cn.qj.cnmrli.swagger.controller"))
//TODO paths():过滤什么路径
// .paths(PathSelectors.ant("/qj/**"))
.build();
}
如何配置Swagger分组与多个分组?
-
groupName("粒桃")
配置多个分组,多实现几个Docket
@Bean
public Docket docketXiaoBai() {
return new Docket(DocumentationType.SWAGGER_2).groupName("程序猿小白");
}
@Bean
public Docket docketXiaoHei() {
return new Docket(DocumentationType.SWAGGER_2).groupName("程序猿小黑");
}
@Bean
public Docket docketXiaoLan() {
return new Docket(DocumentationType.SWAGGER_2).groupName("程序猿小蓝");
}
@Bean
public Docket docketXiaoLv() {
return new Docket(DocumentationType.SWAGGER_2).groupName("程序猿小绿");
}
七、实体类
pojo实体类
package cn.qj.cnmrli.swagger.pojo;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
/**
* @author 青衿
* @Date 2021/2/9 21:38
**/
//@Api(注释信息)
@ApiModel("用户实体类")
public class User {
@ApiModelProperty("用户名")
public String username;
@ApiModelProperty("密码")
public String password;
}
Controller控制体
package cn.qj.cnmrli.swagger.controller;
import cn.qj.cnmrli.swagger.pojo.User;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
/**
* @author 青衿
* @Date 2021/2/9 19:00
**/
@RestController
@Api(tags = "Hello控制器")
public class HelloController {
//Operation接口,是在方法上加上注释
@ApiOperation("Hello控制器")
@GetMapping(value = "/hello")
public String hello() {
return "hello";
}
//Operation接口,是在方法上加上注释
@ApiOperation("user控制器")
//TODO 只要我们的接口中,返回值中存在实体类,他就会被扫描到Swagger中
@PostMapping(value = "/user")
public User user() {
return new User();
}
//Operation接口,是在方法上加上注释
@ApiOperation("Hello2控制器")
@GetMapping(value = "/hello2")
public String hello2(@ApiParam("用户名") String username) {
return "hello" + username;
}
//Operation接口,是在方法上加上注释
@ApiOperation("Postt测试类")
@PostMapping(value = "/postt")
public User postt(@ApiParam("用户名") User user) {
return user;
}
}
八、总结
- 可以通过Swagger给一些比较以及难理解的属性或接口,进行添加注释
- 接口文档实时更新
- 可以在线测试
【 注意点】在正式发布的时候,关闭Swagger!!!出于安全考虑,而且节省运行的内存。