springBoot详解集成Swagger流程
作者:奔走的王木木Sir 时间:2023-02-26 22:23:33
目标:
了解Swagger的作用和概念
了解前后端分离
在springBoot中集成Swagger
Swagger简介
前后端分离
VUE+springBoot
后端 :后端控制层、服务层、数据访问层
前端 :前端控制层、视图层
前后端通过API进行交互
前后端相对独立,松耦合
可以部署在不同的服务器上
产生的问题
前后端集成,前端或者后端无法做到“及时协商,尽早解决”,最终导致问题集中爆发
解决方案
首先定义计划的提纲,并实时跟踪最新的API,降低集成风险
Swagger
号称世界上最流行的API框架
Restful Api 文档在线自动生成器 =>API 文档 与API 定义同步更新
直接运行,可以在线测试API接口;
支持多种语言 (如:Java,PHP等)
官网:https://swagger.io/
SpringBoot集成Swagger
新建一个springboot-web项目
下载maven依赖https://mvnrepository.com/search?q=springfox
<!-- 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>
高版本是没有第5部的测试页面
3.0.0版本的要先在启动类中加上注解@EnableOpenApi先在导入<groupId>io.springfox</groupId><artifactId>springfox-boot-starter</artifactId>
编写Controller,测试运行成功
配置Swagger=》在包Config下
package com.hxl.config;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
@Configuration
@EnableSwagger2 //开启swagger2
public class SwaggerConfig {
}
测试运行:http://localhost:8080/swagger-ui.html
配置Swagger
Swagger实例Bean是Docket,所以通过配置Docket实例来配置Swaggger。
//配置了Swagger的Docket实例
@Bean
public Docket docket(){
return new Docket(DocumentationType.SWAGGER_2);
}
再通过ApiInfo()属性配置文档信息
private ApiInfo apiInfo(){
//作者信息
Contact contact = new Contact("王木木","https://blog.csdn.net/qq_43585922?spm=1000.2115.3001.5343","11@qq.com");
return new ApiInfo(
"Swagger笔记", //标题
"冲冲冲", //描述
"v1.0。0", //版本
"https://blog.csdn.net/qq_43585922?spm=1000.2115.3001.5343", //组织链接
contact, //联系人信息
"Apach 2.0 许可", //许可
"许可链接", //许可连接
new ArrayList<>()//扩展
);
}
Docket关联上ApiInfo
@Bean
public Docket docket(){
return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());
}
启动项目,访问http://localhost:8080/swagger-ui.html
Swagger配置扫描接口
构建Docket时通过select()
方法配置怎么扫描接口。select()
和build()
是一套的
//配置了Swagger的Docket实例
@Bean
public Docket docket(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
/*
RequestHandlerSelectors:要扫描接口的方式
basePackage:指定要扫描的包
any():扫描全部
none():不扫描
withClassAnnotation:扫描类上的注解,参数是一个注解的反射对象
withMethodAnnotation:扫描方法上的注解
path():过滤什么路径
*/
.apis(RequestHandlerSelectors.basePackage("com.hxl.controller"))
//.paths(PathSelectors.ant("/hxl/**"))
.build();
}
我们看之前的运行结构可以看到有base-error-controller
和hello-controller
,一旦使用了上述配置后,运行结果只有hello-controller
配置是否启动Swagger
通过enable()方法配置是否启用swagger
@Bean
public Docket docket(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
//enable是否启动Swagger,默认为true,如果该位false则不能在浏览器中访问
.enable(false)
.select()
/*
RequestHandlerSelectors:要扫描接口的方式
basePackage:指定要扫描的包
any():扫描全部
none():不扫描
withClassAnnotation:扫描类上的注解,参数是一个注解的反射对象
withMethodAnnotation:扫描方法上的注解
path():过滤什么路径
*/
.apis(RequestHandlerSelectors.basePackage("com.hxl.controller"))
//.paths(PathSelectors.ant("/hxl/**"))
.build();
}
Swagger在生产环境中使用,在发布的时候不使用
判断是否是生产环境
注入enable()值
当我们有多个生产环境时。比如说application-dev.yaml
和application-pro.yaml
。动态设置当前项目处于dev时显示swagger,Pro是不显示
#哪个环境生效
spring.profiles.active=dev
设置我们的dev走8081,默认走8080,pro走8082
然后修改我们的配置
@Bean
public Docket docket(Environment environment){
//设置显示的Swagger环境
Profiles profiles = Profiles.of("dev", "test");
//通过 判断是否处在自己设定的环境中
boolean flag = environment.acceptsProfiles(profiles);
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
//这里变成了flag
.enable(flag)
.select()
.apis(RequestHandlerSelectors.basePackage("com.hxl.controller"))
.build();
}
此时我们就发现,如果我们走默认的8080是没有Swagger的,走8081才有
配置API文档的分组
@Bean
public Docket docket(Environment environment){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.groupName("王木木");
//其余配置省略
}
启动项目就发现我们的组别有了
如果有多个分组怎么办?只需要配置多个docket
即可
//其他的环境需要自己填
@Bean
public Docket docket1(){
return new Docket(DocumentationType.SWAGGER_2).groupName("天");
}
@Bean
public Docket docket2(){
return new Docket(DocumentationType.SWAGGER_2).groupName("狼");
}
实体类配置
创建一个实体类
package com.hxl.pojo;
public class User {
public String username;
public String password;
}
只要这个实体在请求接口的返回值上,就可以映射到实体项中
//只要我们的接口中,返回值存在实体类,他就会扫描到Swagger中
@PostMapping("/user")
public User user(){
return new User();
}
测试
此时发现我们的Model中有了User。如果有中文的注释,只需要在加两个注解
package com.hxl.pojo;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
//@Api("注释")
@ApiModel("用户实体类")
public class User {
@ApiModelProperty("姓名")
public String username;
@ApiModelProperty("密码")
public String password;
}
测试
常用的注解
Swagger的所有注解定义在io.swagger.annotations包下
Swagger注解 | 简单说明 |
---|---|
@Api(tags = “xxx模块说明”) | 作用在模块类上 |
@ApiOperation(“xxx接口说明”) | 作用在接口方法上 |
@ApiModel(“xxxPOJO说明”) | 作用在模型类上:如VO、BO |
@ApiModelProperty(value = “xxx属性说明”,hidden = true) | 作用在类方法和属性上,hidden设置为true可以隐藏该属性 |
@ApiParam(“xxx参数说明”) | 作用在参数、方法和字段上 |
注解在类上的可以看一下上面的,接下来看注解在接口方法上,以及参数上
@ApiOperation("王木木的接口")
@PostMapping("/hxl")
public String hxl(@ApiParam("用户名")String username){
return username;
}
在这里还可以进行测试
小结
我们可以通过Swagger给一些比较难理解的属性或者接口增加注释信息
接口文档实时更新
可以在线测试
在正式发布的时候一定要关闭Swagger《安全;节省运行的内存》
来源:https://blog.csdn.net/qq_43585922/article/details/125458669
![](/images/zang.png)
![](/images/jiucuo.png)
猜你喜欢
C# 线程同步的方法
UGUI绘制多点连续的平滑曲线
Struts和servlet不能共存问题解决方法
Unity的IPostBuildPlayerScriptDLLs实用案例深入解析
Gradle配置教程之自定义APK名称与输出路径
![](https://img.aspxhome.com/file/2023/3/102583_0s.jpg)
SpringDataJPA在Entity中常用的注解介绍
Java实现微信发红包
![](https://img.aspxhome.com/file/2023/1/67111_0s.jpg)
详解java中String、StringBuilder、StringBuffer的区别
Java(基于Struts2) 分页实现代码
Javacsv实现Java读写csv文件
在maven中引入本地jar包的步骤
AndroidStudio3.6.1打包jar及AndroidStudio4.0打包jar的一系列问题及用法
![](https://img.aspxhome.com/file/2023/0/126740_0s.png)
详解 Java Maximum redirects (100) exceeded
java实现双色球机选号码生成器
springboot Interceptor拦截器excludePathPatterns忽略失效
![](https://img.aspxhome.com/file/2023/9/74879_0s.jpg)
常用类之TCP连接类-socket编程
Android使用TextView跑马灯效果
![](https://img.aspxhome.com/file/2023/0/84730_0s.gif)
java 数据结构之删除链表中的元素实例代码
Java基础学习之集合底层原理
![](https://img.aspxhome.com/file/2023/0/86820_0s.png)