Swagger简介
故事还是要从前后端分离讲起啊
**前后端分离:**VUE+SpringBoot 基本上都用这一套
**后端时代:**前端只用管理静态页面,html===》后端,使用模版引擎 jsp=》后端主力
前后端分离时代:
后端:后端控制层,服务层,数据访问层【后端团队】
前端:前端控制层,视图层,【前端团队】
伪造后端数据,json,已经存在数据,不需要后端,前端工程依旧可以跑起来
前后端如何交互 ====》API
前后端相对独立,松耦合
前后端甚至可以部署在不同的服务器上
产生一个问题:
前后端联调,前端和后端人员无法做到及时协商,解决问题,导致问题爆发
需要一个东西可以解决这个问题
解决问题:
首先指定计划,实时更新API,较低集成风险
早些年:指定word计划文档
前后端分离:
前端测试后端接口:postman
后端提供接口,需要使用更新最新的消息及改动!
Swagger:
号称世界上最流行的api框架
Restful Api文档在线自动生成工具==》api文档和api定义开发
直接运行,可以在线测试api接口;
执行多种语言(c#,java,php)
在项目中使用Swagger需要Springfox
swagger2
ui
SpringBoot集成Swagger
新建项目:SpringBoot-Swagger
导入相关依赖
<!-- 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>
新版(3.0)的直接加入启动器
<dependency> <groupId>io.springfox</groupId> <artifactId>springfox-boot-starter</artifactId> <version>3.0.0</version> </dependency>
创建一个helloword的项目
配置Swagger==>就可以启动看看效果了 3.0版本后不需要在加入@enableopenapi,和@enableswagger2这两个注解,
package com.hyc.springbootswagger.config; import org.springframework.context.annotation.Configuration; import springfox.documentation.swagger2.annotations.EnableSwagger2; @Configuration public class swaggerconfig { }
//localhost:8080/swagger-ui/index.html
配置Swagger
配置呢,Swagger有自己的实例
我们使用docket来配置swagger的基本信息
package com.hyc.springbootswagger.config; import org.springframework.context.annotation.Configuration; import springfox.documentation.swagger2.annotations.EnableSwagger2; @Configuration public class swaggerconfig { }
应为没有set方法所以我们只能用构造器,貌似,还有一个什么biuder可以使用,有机会去试试
swagger配置扫描接口
select()来设置扫描
扫描接口配置的方法:
apis:
RequestHandlerSelectors扫描接口的方式
basePackage指定扫描包
any()扫描全部
none()不扫描
withclassannotation 扫描类的注解(里面必须放注解的反射对象)
path:过滤哪里什么路径
paths(PathSelectors.ant("/hyc/**"))
.select() //指定我们需要基于什么包扫描 .apis(RequestHandlerSelectors.basePackage("com.hyc.springbootswagger.controller")) .build();
使用了自定义,那么swagger就不会去扫描其他的位置,会扫描你指定的这个报下的请求
可以发现,现在只有controller下的请求才会被扫描
是否开启Swagger
.enable(false)//eanble决定了是否启动swagger
如果为false那我们就无法进入swagger-ui/index.html了
如何让我在测试的时候用swagger,发布的时候不用swagger
environment.acceptsProfiles来判断是否处在环境中
//配置swagger要使用的环境
Profiles profiles = Profiles.of("dev", "test");
用profiles来配置使用环境
.enable(flag)//eanble判断是否启动swagger
api分组
分组,如何分组,
.groupName("胡宇辰")
分组,如何多个分组?,我有多个docket就可以有多个.groupName
@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()) .groupName("胡宇辰") .enable(flag)//eanble决定了是否启动swagger .select() //指定我们需要基于什么包扫描 /*apis * RequestHandlerSelectors扫描接口的方式 * basePackage指定扫描包 * any()扫描全部 * none()不扫描 * withclassannotation 扫描类的注解(里面必须放注解的反射对象) * */ .apis(RequestHandlerSelectors.basePackage("com.hyc.springbootswagger.controller")) /*path:过滤哪里什么路径 * * */ // .paths(PathSelectors.ant("/hyc/**")) .build(); } @Bean public Docket docket1(Environment environment){ return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) .groupName("小刘"); } @Bean public Docket docket2(Environment environment){ return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) .groupName("小郑"); }
配置多个组
就是有很多个docket,
效果:
实体类
只要我们的接口中,有接口返回的是实体类,那么就是会被swagger扫描
我们写一个方法
@PostMapping("/user")
public User user(){
return new User();
}
返回的是实体类user,user里有两个字段,name和age
页面效果图:
那我们看到的如@API这些注解是干什么的呢?
Swagger注解
用来解释类的用@Apimodel
@ApiModel("用户信息实体类")
public class User{
}
用来解释类中的属性用@ApiModelProperty()
@ApiModelProperty("用户名字")
public String name;
@ApiModelProperty("用户年龄")
public int age;
小疑问:我用private修饰的变量这么写就不显示,怎么办?
解决方案:写在get方法上就可以有效果了
Swagger测试接口
测试接口十分好用,
我们可以测试自己的接口是否有效
小测试:
测试接口:
@PostMapping("/userJY")
public User user2(String name,int age){
User user = new User(name,age);
return user;
}
测试页面步骤图
查看提交后的接口信息
Swagger总结
Swagger最重大的使命就是使前后端人员之间的和谐关系有所好转
接口文档可以实时更新
可以在线测试后端接口,这个功能好评,爽的一批