本文介绍了Swagger作为流行的API框架，用于生成RESTful API文档并支持在线测试。在SpringBoot项目中集成Swagger，包括配置扫描接口、设置API分组以及实体类的注解，实现前后端分离的API管理。同时，讨论了如何根据环境配置在生产环境中关闭Swagger，以及如何通过Docket和ApiInfo进行详细配置。
简介
使用swagger时启动类不能使用@ComponentScan扫描包注解,否则无法识别控制层api接口
标准的前后端分离为:
Vue+Springboot
先前后端时代: 前端只用管理静态页面
前后端分离时代:
- 后端 后端控制层,后盾服务层,数据访问层
- 前端: 前端控制层,视图层
伪造后端数据,利用json字符串,这样前端工程依然可以跑起来
前后端如何进行交互?===> API
前后端的好处:前后端相对独立,松耦合;
前后端甚至可以部署在不同的服务器上面
这样也就会产生一个交互的问题:
前端人员和后端人员无法及时集成联调
解决方案:
首先指定schema(计划提纲),实时更新最新API.来降低集成风险
早些年使用word文档进行实时更新来解决交流问题
前后端分离:
前端测试后端接口: postman(专业的第三方测试工具)
后端提供接口,需要实时更新最新的消息以及改动
所以,Swagger就诞生了
Swagger号称世界上最流行的API框架
Restful风格 API文档在线自动生成工具=>API文档与api定义同步更新
直接运行,可以在线测试API接口;
支持多种语言:java php
官网:https://swagger.io/
在项目中使用swagger需要springbox;
swagger2
UI
springboot集成swagger
一般springboot项目多模块集成swagger，可以直接创建一个公共模块comment来实现swagger，然后在其他模块的pom.xml配置文件中引入公共模块的依赖
<dependency>
<groupId>com.XXXX</groupId>
<artifactId><swagger实现模块名></artifactId>
<version>0.0.1-SNAPSHOT</version>
</dependency>
并在主启动类上添加注解@ComponentScan(basePackages = {“com.xg”})配置类的模块需要和启动类所在的模块包名一致,比如(com.xg),如果不一样就扫描不到主启动类中的控制层接口
同样首先新建一个springboot项目
然后导入相关的依赖: (3.0.0版本进不去)
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
创建一个最基本的hello工程并配置swagger==>Config
在Config包中新建一个SwaggerConfig类,这里仅开启默认,并没有真正配置,注意:
要想配置到springboot中就必须要加上@Configuration
@Configuration //令配置生效
@EnableSwagger2 //开启Swagger2
public class SwaggerConfig {
}
然后测试一下:
配置Swagger
Swagger的bean实例:Docket;
docket实例又需要一个apiinfo实例,这个实例用来指明页面信息,以下为例:
@Configuration //令配置生效
@EnableSwagger2 //开启Swagger2
public class SwaggerConfig {
@Bean //配置Swagger的Docket实例
public Docket docket(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo());
}
//配置Swagger信息 apiInfo
private ApiInfo apiInfo(){
//作者信息
Contact contact = new Contact("XI哥", "", "2045807586@qq.com");
return new ApiInfo(
"XI哥的swaggerAPI文档",
"Api Documentation",
"v1.0",
"urn:tos",
contact,
"Apache 2.0",
"http://www.apache.org/licenses/LICENSE-2.0",
new ArrayList<>());
}
}
Swagger配置扫描接口
Docket.select()
@Bean //配置了Swagger的Docket实例
public Docket docket(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
//RequestHandlerSelectors配置要扫描接口的方式
// basePackage代表具体扫描哪个包,源码中还有any(全部)以及none(全不)
//还有withClassAnnotation:扫描类上的注解 参数为注解的反射对象
//withMethodAnnotation:扫描方法上的注解
// withMethodAnnotation(RestController.class)代表只会扫描带有@RestController注解的方法
.apis(RequestHandlerSelectors.basePackage("com.xige.swagger.controller"))
//paths 路径,也就是通过路径去过滤
.paths(PathSelectors.ant("/xige/**"))
.build();//
}
配置是否启动Swagger只需要一句: Docket.enable(false)
拓展:
只希望swagger只在生产环境中使用,发布的时候不使用应该如何进行设置:
思路:首先需要判断是否为生产环境 flag=false
然后将flag赋值给enable即可
首先准备两套不同的环境: dev为测试,pro为上线环境
默认环境中设置具体使用哪一套:
spring.profiles.active=dev
然后在方法中注入参数Environment,
通过profiles.of()方法显示swagger环境再利用environment.acceptsProfiles(profiles)来进行检测判断,最后将返回的boolean值给Docket.enable()方法即可
配置API分组
配置分组只需要一个方法:
.groupName("hello")
那么问题来了,如何配置多个分组呢?
只需要配置多个Docket即可:
@Configuration //令配置生效
@EnableSwagger2 //开启Swagger2
public class SwaggerConfig {
@Bean
public Docket docket1(){
return new Docket(DocumentationType.SWAGGER_2).groupName("A");
}
@Bean
public Docket docket2(){
return new Docket(DocumentationType.SWAGGER_2).groupName("B");
}
@Bean
public Docket docket3(){
return new Docket(DocumentationType.SWAGGER_2).groupName("C");
}
@Bean //配置了Swagger的Docket实例
public Docket docket(Environment environment){
//设置要显示的swagger环境
Profiles profiles = Profiles.of("dev","test");
//通过environment.acceptsProfiles(profiles)监听判断是否处于自己设定的环境当中:
boolean b = environment.acceptsProfiles(profiles);
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.groupName("hello")
.enable(b)
.select()
//RequestHandlerSelectors配置要扫描接口的方式
// basePackage代表具体扫描哪个包,源码中还有any(全部)以及none(全不)
//还有withClassAnnotation:扫描类上的注解 参数为注解的反射对象
//withMethodAnnotation:扫描方法上的注解
// withMethodAnnotation(RestController.class)代表只会扫描带有@RestController注解的方法
.apis(RequestHandlerSelectors.basePackage("com.xige.swagger.controller"))
//paths 路径,也就是通过路径去过滤
.paths(PathSelectors.ant("/xige/**"))
.build();//
}
//配置Swagger基本信息 apiInfo
private ApiInfo apiInfo(){
//作者信息
Contact contact = new Contact("XI哥", "", "2045807586@qq.com");
return new ApiInfo(
"XI哥的swaggerAPI文档",
"Api Documentation",
"v1.0",
"urn:tos",
contact,
"Apache 2.0",
"http://www.apache.org/licenses/LICENSE-2.0",
new ArrayList<>());
}
}
实体类配置:
所见即所得
POJO层:
@Data
@AllArgsConstructor
@NoArgsConstructor
@ApiModel("用户实体类")
public class User {
@ApiModelProperty("用户名")
public String UserName;
@ApiModelProperty("密码")
public String Password;
}
controller层:
@RestController
public class HelloController {
@GetMapping(value = "/hello")
public String hello1(){
return "hello";
}
//只要我们的接口的返回值中存在实体类,它就会扫描到Swagger中
@PostMapping(value = "/user")
public User hello(){
return new User();
}
@ApiOperation("hello控制类Controller")
@GetMapping(value = "/hello2")
public String hello(@ApiParam("用户名") String username){
return "hello"+username;
}
@ApiOperation("Post测试类")
@PostMapping(value = "/postt")
public User hello2(@ApiParam("用户名") User user){
return user;
}
}
效果:
其中有些传参测试可以直接在swagger中进行:
输入参数之后点击execute就可以实时测试参数传递,输出信息包括报错信息都会在输出栏进行显示:
总结:
我们可以通过swagger给一些比较难理解的属性或者接口,增加注释信息
接口可以实时更新
可以在线测试
唯一注意的就是在项目正式发布的时候关闭swagger
扫一扫
2万+
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
