前后端分离必备工具:Swagger快速搞定(整合SpringBoot详细教程)
本文根据
狂神
教学视屏同步所做笔记
目录
- 一、Swagger简介
- 1. 前后端分离
- 2. Swagger引入
- 二、SpringBoot集成Swagger
- 1. 新建springboot项目
- 2. 导入Swagger依赖
- 3. 编写HelloController测试
- 4. 编写Swagger配置类
- 5. 测试进入Sawgger页面
- 6. 配置Swagger API信息
- 7. 配置Swagger自定义扫描接口
- 8. 配置是否启动Swagger
- 9. 配置API文档分组
- 1. 设置默认组名
- 2. 配置多个组
- 10. 配置Model实体类
- 1. 新建实体类
- 2. 编写对应请求接口
- 3. 启动测试
- 4. 常用注解
- 11. 测试Swagger的使用
- 1. 测试传参
- 2. 测试错误
学习目标:
- 了解Swagger的作用和概念
- 了解前后端分离
- SpringBoot继承Swagger
一、Swagger简介
1. 前后端分离
后端时代:前端只用管理静态页面;html等静态资源交给后端通过模板引擎进行渲染
前后端分离时代:
- 后端:控制层controller、服务层service、数据访问层dao
- 前端:前端控制层、视图层
- 前后端交互:通过API接口
- 前后端相对独立,松耦合,甚至可以部署在不同的服务器上
随之产生的问题:前后端联调,前端人员和后端人员无法做到及时协商,尽早解决
解决方案:
- 首先指定
schema
,实时更新最新的API,降低集成风险 - 早些年:指定word计划文档
- 前后端分离:
- 前端测试后端接口数据是否正确:postman
- 后端提供接口,需要实时更新最新的消息和改动
于是Swagger应运而生
2. Swagger引入
- 号称历史上最流行的api框架
- RestFul Api文档在线生成工具=》Api文档与Api定义同步更新
- 直接运行,可以在线测试Api接口
- 支持多种语言
官网:https://swagger.io/
二、SpringBoot集成Swagger
1. 新建springboot项目
首先新建一个spirngboot项目,勾选组件时勾选
Spring-Web
2. 导入Swagger依赖
springfox-swagger2
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger2</artifactId><version>3.0.0</version>
</dependency>
springfox-swagger-ui
<!-- 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. 编写HelloController测试
我们编写一个controller来测试一下项目是否搭建成功,在主程序同级目录下新建
controller
包,其中新建HelloController
类
package com.zsr.controller;import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;@RestController
public class HelloController {@RequestMapping("/hello")public String hello() {return "hello";}
}
然后启动主程序,访问localhost:8080/hello
,出现如下结果即成功
4. 编写Swagger配置类
在主程序同级目录下新建
config
包,其中新建SwaggerConfig
配置类
- 记住用
@Configuration
注解注明这是配置类- 同时用
@EnableSwagger2
注解开启Swagger2
package com.zsr.config;import org.springframework.context.annotation.Configuration;
import springfox.documentation.swagger2.annotations.EnableSwagger2;@Configuration
@EnableSwagger2//开启Swagger2
public class SwaggerConfig {}
5. 测试进入Sawgger页面
重启主程序,访问
localhost:8080/swagger-ui.html
启动报错:@EnableSwagger2
注解找不到,但是已经导入了对应的jar包
这时候降级为2.9.2
即可使用
<!-- 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>
再次启动主程序即可成功,然后访问localhost:8080/swagger-ui.html
,即可进入到以下界面
这个界面是Swagger为我们提供的ui界面,我们可以在源码中找到它
6. 配置Swagger API信息
在Swagger提供的ui界面,其中的
Swagger
信息模块我们可以自定义信息内容我们只需要在Swagger配置类
SwaggerConfig
中实例化Docket
类队对象的bean实例,通过配置ApiInfo
类的信息然后传入Docket的bean实例即可
package com.zsr.config;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.service.VendorExtension;
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实例@Beanpublic Docket docket() {return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());//配置Swagger信息}//配置Swagger信息private ApiInfo apiInfo() {return new ApiInfo("Baret-H","我的Swagger API文档","1.0","https://bareth.blog.csdn.net/",new Contact("Baret-H", "https://bareth.blog.csdn.net/", "1412578784@qq.com"),//作者信息"Apache 2.0","http://www.apache.org/licenses/LICENSE-2.0",new ArrayList<VendorExtension>());}
}
重启主程序测试,可以看到Swagger信息已经变更成我们定义的信息
7. 配置Swagger自定义扫描接口
我们在这个ui界面中,可以看到扫描了两个controller接口;
一个是默认的
/error
请求,也就是我们启动springboot主程序未加配置默认访问8080端口的默认controller
另一个是我们自己写的
/hello
请求,对应着HelloController
,由于我们用的@RequsetMapping
注解,所以请求的方式有以上的六种
接下来我们自己配置以下要扫描的接口
@Bean
public Docket docket() {return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())//配置Swagger信息.select()/*** apis():指定扫描的接口* RequestHandlerSelectors:配置要扫描接口的方式* basePackage:指定要扫描的包* any:扫面全部* none:不扫描* withClassAnnotation:扫描类上的注解(参数是类上注解的class对象)* withMethodAnnotation:扫描方法上的注解(参数是方法上的注解的class对象)*/.apis(RequestHandlerSelectors.basePackage("com.zsr.controller"))/*** paths():过滤路径* PathSelectors:配置过滤的路径* any:过滤全部路径* none:不过滤路径* ant:过滤指定路径:按照按照Spring的AntPathMatcher提供的match方法进行匹配* regex:过滤指定路径:按照String的matches方法进行匹配*/.paths(PathSelectors.ant("/zsr/**")).build();
}
其中.select().apis.paths.build
是一套组合进行使用
然后我们启动主程序访问localhost:8080/swagger-ui.html
进行测试
可以发现No opertations defined in spec
,这是因为我们过滤了/zsr
下的所有controller
我们将过滤条件更改为过滤全部路径
.paths(PathSelectors.any)
再次启动主程序访问localhost:8080/swagger-ui.html
可以看到只显示了我们上述自定义的com.zsr.controller
下的接口HelloController
.apis(RequestHandlerSelectors.basePackage("com.zsr.controller"))
8. 配置是否启动Swagger
我么通过
Docket
对象的.enable
方法来配置swagger是否启动
@Bean
public Docket docket() {return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())//配置Swagger信息.enable(false)//配置是否启动swagger,默认为true.select().apis(RequestHandlerSelectors.basePackage("com.zsr.controller")).paths(PathSelectors.ant("/zsr/**")).build();
}
更改为false后启动测试一下,查看控制台,无法进入到swagger页面
如果我们有这样一个需求:希望Swagger在开发环境中,在正式环境时不能使用
- 首先要判断是不是开发环境,可以设置一个flag表示用来表示:flag=1即表示生产环境
- 然后将flag的值传给
enable(flag)
首先在resources
目录下新建两种springboot配置文件:
开发环境:
application-dev.properties
server.port=8081
正式环境:
application-pro.properties
server.port=8082
然后在主配置文件application.properties
中激活开发环境
spring.profiles.active=dev
然后我们到SwaggerConfig
中的docket()
方法中添加代码:
首先给该方法传一个参数
Environment
的实例Environment environment
首先设置药配置的Swagger环境:这里可以添加多个环境
Profiles profiles = Profiles.of("dev", "test");
然后通过
environment.acceptsProfiles
方法判断是否处在上一步设定的dev/test
环境中,返回一个boolean
的值,我们用flag
接收boolean flag = environment.acceptsProfiles(profiles);
然后修改
enable
中的参数为flag
,即通过flag来判断是否开启Swagger
.enable(flag)//通过flag判断是否开启
完整代码:
@Configuration
@EnableSwagger2//开启Swagger2
public class SwaggerConfig {//配置Swagger的Docket的bean实例@Beanpublic 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())//配置Swagger信息.enable(flag)//通过flag判断是否开启.select().apis(RequestHandlerSelectors.basePackage("com.zsr.controller")).paths(PathSelectors.ant("/zsr/**")).build();}//配置Swagger信息private ApiInfo apiInfo() {return new ApiInfo("Baret-H","我的Swagger API文档","1.0","https://bareth.blog.csdn.net/",new Contact("Baret-H", "https://bareth.blog.csdn.net/", "1412578784@qq.com"),//作者信息"Apache 2.0","http://www.apache.org/licenses/LICENSE-2.0",new ArrayList<VendorExtension>());}
}
然后启动主程序测试:由于激活了dev
开发环境,所以访问localhost:8081/swagger-ui.html
成功开启swagger,如果我们修改主配置文件,激活pro
正式发布环境
spring.profiles.active=pro
再次重启主程序测试,访问端口8082对应的地址localhost:8082/swagger-ui.html
无法进入,因为pro
环境不在我们配置的test/dev
环境中,所以无法开启
9. 配置API文档分组
1. 设置默认组名
可以看到,我们默认只有一个组且组名为default
我们可以在docket
通过.groupName
中设置组名
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())//配置Swagger信息.groupName("zsr").enable(true)//配置是否启动swagger,默认为true.select().apis(RequestHandlerSelectors.basePackage("com.zsr.controller")).paths(PathSelectors.any()).build();
}
重启测试,可以看到组名更改为zsr
2. 配置多个组
上述我们成功修改了组名,但是只有一个组,如果我们想要多个组呢?
观察代码可以知道,一个
Docket
实例就对应着一个组,因此我们配置多个docket就对应着多个组
我们新增两个Docket
的bean实例
@Bean
public Docket docket1() {return new Docket(DocumentationType.SWAGGER_2).groupName("Baret-H");
}@Bean
public Docket docket2() {return new Docket(DocumentationType.SWAGGER_2).groupName("钟");
}
再次重启测试,就可以看到多个组并选择
10. 配置Model实体类
1. 新建实体类
在主程序同级目录下新建
pojo
包,其中新建User
实体类
package com.zsr.pojo;public class User {public String username;public String password;
}
2. 编写对应请求接口
编写完实体类,我们在model中还是看不到的,我们还需在
HelloController
中新增一个方法返回实体类的实例对象即可映射到实体项中
@GetMapping("/getUser")
public User getUser() {return new User();
}
3. 启动测试
成功显示实体类User
4. 常用注解
我们可以在实体类上和其属性上添加注解来添加对应的注释
@ApiModel
为类添加注释@ApiModelProperty
为类属性添加注释
package com.zsr.pojo;import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;@ApiModel("用户实体")
public class User {@ApiModelProperty("用户名")public String username;@ApiModelProperty("密码")public String password;
}
重启测试,即可以看到注释信息
我们同样可以在
Controller
类和其中的方法上添加相应的注解
@Api(tags = "Hello控制类")
@RestController
public class HelloController {@RequestMapping("/hello")public String hello() {return "hello";}@ApiOperation("hello控制类")@GetMapping("/getUser")public User getUser() {return new User();}
}
重启即可看到对应的注解
11. 测试Swagger的使用
1. 测试传参
我们在
HelloController
中新增一个方法,参数为username
,可以用@ApiParam
给该参数添加注解
@GetMapping("/username")
public String getUserName(@ApiParam("用户名") String username) {return username;
}
重启测试,可以看到我们添加的注释
我们可以简单测试一下,点击Try it out
;然后以json的格式输入用户名,然后点击Execute
执行
可以看到报错了,这是因为我们是使用的是Get
方式:是通过URL的方式传递的,而不是通过请求体单独传参
我们将代码修改一下,将GetMapping
改为PostMapping
@PostMapping("/username")
public String getUserName(@ApiParam("用户名") String username) {return username;
}
再次以json的格式输入参数username,可以看到成功了
2. 测试错误
我们在
HelloController
中新增一个方法,参数为User
,可以用@ApiParam
给该参数添加注解
然后运行测试
找到对应的controller,点击Try it out
测试,输入用户名和密码然后点击Excute
可以看到我们请求的URL
完全正确,但是Response body
相应体中用户名和密码都为空,这是因为我们的实体类没有添加对应的GET和SET方法
,我们添加上去
package com.zsr.pojo;import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;@ApiModel("用户实体")
public class User {@ApiModelProperty("用户名")public String username;@ApiModelProperty("密码")public String password;public String getUsername() {return username;}public void setUsername(String username) {this.username = username;}public String getPassword() {return password;}public void setPassword(String password) {this.password = password;}
}
再次启动测试,成功!
如果我们修改一下代码
@PostMapping("/post")
private User postUser(User user) {int i = 100 / 0;return user;
}
此时测试肯定会报错,我们测试看看,可以看到500
错误
由此可见,swagger可以让我们很容易的进行前后端的交互测试
前后端分离必备工具:Swagger快速搞定(整合SpringBoot详细教程)相关推荐
- 怎么提取伴奏?只要三招即可快速搞定,附带详细教程
有没有跟我一样喜欢唱歌的小伙伴呀?我闲暇时就喜欢在k歌平台上录歌并分享给好友,但有时因为一些个别原因,部分歌曲找不到伴奏,从各大音乐平台上下载下来的音频也是带有原唱,这可就无法展现我的唱歌" ...
- 若依前后端分离+帆软报表 快速建立网站及后台管理功能
若依前后端分离+帆软报表 快速建立网站及后台管理功能 架构 1.后台管理:若依作为后台管理框架,使用它自带的用户,角色,组织架构管理模块,在此基础上通过代码生成功能二次开发增加业务模块:使用帆软报表快 ...
- Jeecg-Boot 快速开发平台,前后端分离—开发工具安装
目录索引: 后端开发工具 前端开发工具 Nodejs镜像 WebStorm入门配置 JeecgBoot采用前后端分离的架构,官方推荐开发工具前端开发: Webstrom 或者 IDEA后端开发: Ec ...
- 前后端分离必备的接口规范,十分接地气
1. 前言 随着互联网的高速发展,前端页面的展示.交互体验越来越灵活.炫丽,响应体验也要求越来越高,后端服务的高并发.高可用.高性能.高扩展等特性的要求也愈加苛刻,从而导致前后端研发各自专注于自己擅长 ...
- 前后端分离 常用工具汇总
文章目录 一.数据框架 1. vue 2. react 二.UI框架 2.1. element 2.2. element-plus 2.3. Ant Design Vue 2.4. Ant Desig ...
- Vue前后端分离项目与vue-baidu-map百度地图api整合使用步骤
1.首先 必须在index.html文件中引入 这段脚本,不然就算执行了下面的,地图也会不显示,这个是坑. $ npm install vue-baidu-map --save npm安装完后在vu ...
- 讲解开源项目:一步步跑起来个 Java 前后端分离的人力资源管理系统
本文适合刚学习完 Java 语言基础的人群,跟着本文可了解和运行项目,本示例是在 Windows 操作系统下演示. 本文作者:HelloGitHub-秦人 大家好!这里是 HelloGitHub 推出 ...
- 前后端分离:SpringBoot治好了我的时间内耗
1.前后端分离为了什么 1.1前言 本文作为系列文章的第一篇,是铁柱在工作之余对自我学习的总结,以下内容是搭建基础的前后端分离的Demo来展开的,需要对MySQL,Spring,SpringMVC ...
- JAVA外卖项目第九天 前后端分离和项目部署优化
瑞吉外卖项目优化-Day03 课程内容 前后端分离开发 Yapi Swagger 项目部署 前言 当前项目中,前端代码和后端代码混合在一起,是存在问题的,存在什么问题呢? 主要存在以下几点问题: 1) ...
最新文章
- Vim----ma6174
- Openstack组件部署 — Nova_Install and configure a compute node
- [CareerCup][Google Interview] 找出现次数
- 闪存我自己来——HDS公布闪存路线图
- iOS之常用的正则表达式
- python序列切片
- Float 运算的怪异性
- iOS 网络通信01
- 事件驱动的过程链方法(EPCs)
- 博士毕业论文英文参考文献换行_Endnote教程丨本科研究生毕业论文参考文献格式模板,一键搞定...
- 第二人生的源码分析(9)登录界面显示
- 关于checkbox的removeClass属性
- /proc/cpuinfo参数说明查看CPU参数
- Datawhale组队学习——Pytorch进阶训练技巧
- 最后一本书 第六章课后练习3,4
- 十进制与二进制的转换
- Latex中IOP模板下amsmath包报错
- 安卓自定义音量键_iPhone 为啥要一直保留“静音键”?
- Facebook 新款AR眼镜都有哪些技术创新?
- 安卓多媒体应用-通知
热门文章
- ireport如何给static text加边框_html amp;amp; css 解决li浮动边框为2的问题
- MYSQL局域网访问设置
- shell编程_linux
- pytorch学习笔记(九):PyTorch结构介绍
- LeetCode简单题之字符的最短距离
- LeetCode简单题之买卖股票的最佳时机
- Mask-RCNN技术解析
- 道路场景语义分割算法
- 客快物流大数据项目(二十二):Docker环境中安装软件
- 2021年大数据Flink(三十五):​​​​​​​Table与SQL ​​​​​​案例二