SpringBoot | 第十章:Swagger2的集成和使用
2019独角兽企业重金招聘Python工程师标准>>>
前言
前一章节介绍了
mybatisPlus
的集成和简单使用,本章节开始接着上一章节的用户表,进行Swagger2
的集成。现在都奉行前后端分离
开发和微服务大行其道,分微服务及前后端分离后,前后端开发的沟通成本就增加了。所以一款强大的RESTful API
文档就至关重要了。而目前在后端领域,基本上是Swagger
的天下了。
Swagger2介绍
Swagger
是一款RESTful
接口的文档在线自动生成、功能测试功能框架。一个规范和完整的框架,用于生成、描述、调用和可视化RESTful
风格的Web服务,加上swagger-ui
,可以有很好的呈现。
SpringBoot集成
这里选用的swagger版本为:2.8.0
0.pom依赖
<!--swagger --><dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger2</artifactId><version>2.8.0</version></dependency><dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger-ui</artifactId><version>2.8.0</version></dependency>
1.编写配置文件(Swagger2Config.java)
主要是添加注解
@EnableSwagger2
和定义Docket
的bean类。
@EnableSwagger2
@Configuration
public class SwaggerConfig {//是否开启swagger,正式环境一般是需要关闭的,可根据springboot的多环境配置进行设置@Value(value = "${swagger.enabled}")Boolean swaggerEnabled;@Beanpublic Docket createRestApi() {return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())// 是否开启.enable(swaggerEnabled).select()// 扫描的路径包.apis(RequestHandlerSelectors.basePackage("cn.lqdev.learning.springboot.chapter10"))// 指定路径处理PathSelectors.any()代表所有的路径.paths(PathSelectors.any()).build().pathMapping("/");}private ApiInfo apiInfo() {return new ApiInfoBuilder().title("SpringBoot-Swagger2集成和使用-demo示例").description("oKong | 趔趄的猿")// 作者信息.contact(new Contact("oKong", "https://blog.lqdev.cn/", "499452441@qq.com")).version("1.0.0").build();}
}
3.添加文档内容(一般上是在Controller
,请求参数上进行注解,这里以上章节的UserController
进行配置)
UserController
/*** 用户控制层 简单演示增删改查及分页* 新增了swagger文档内容 2018-07-21* @author oKong**/
@RestController
@RequestMapping("/user")
@Api(tags="用户API")
public class UserController {@AutowiredIUserService userService;@PostMapping("add")@ApiOperation(value="用户新增")//正常业务时, 需要在user类里面进行事务控制,控制层一般不进行业务控制的。//@Transactional(rollbackFor = Exception.class)public Map<String,String> addUser(@Valid @RequestBody UserReq userReq){User user = new User();user.setCode(userReq.getCode());user.setName(userReq.getName());//由于设置了主键策略 id可不用赋值 会自动生成//user.setId(0L);userService.insert(user);Map<String,String> result = new HashMap<String,String>();result.put("respCode", "01");result.put("respMsg", "新增成功");//事务测试//System.out.println(1/0);return result;}@PostMapping("update")@ApiOperation(value="用户修改") public Map<String,String> updateUser(@Valid @RequestBody UserReq userReq){if(userReq.getId() == null || "".equals(userReq.getId())) {throw new CommonException("0000", "更新时ID不能为空");}User user = new User();user.setCode(userReq.getCode());user.setName(userReq.getName());user.setId(Long.parseLong(userReq.getId())); userService.updateById(user);Map<String,String> result = new HashMap<String,String>();result.put("respCode", "01");result.put("respMsg", "更新成功");return result;}@GetMapping("/get/{id}")@ApiOperation(value="用户查询(ID)") @ApiImplicitParam(name="id",value="查询ID",required=true)public Map<String,Object> getUser(@PathVariable("id") String id){//查询User user = userService.selectById(id);if(user == null) {throw new CommonException("0001", "用户ID:" + id + ",未找到");}UserResp resp = UserResp.builder().id(user.getId().toString()).code(user.getCode()).name(user.getName()).status(user.getStatus()).build();Map<String,Object> result = new HashMap<String,Object>();result.put("respCode", "01");result.put("respMsg", "成功");result.put("data", resp);return result;}@GetMapping("/page")@ApiOperation(value="用户查询(分页)") public Map<String,Object> pageUser(int current, int size){//分页Page<User> page = new Page<>(current, size);Map<String,Object> result = new HashMap<String,Object>();result.put("respCode", "01");result.put("respMsg", "成功");result.put("data", userService.selectPage(page));return result;}}
UserReq.java
@Data
@Builder
@NoArgsConstructor
@AllArgsConstructor
//加入@ApiModel
@ApiModel
public class UserReq {@ApiModelProperty(value="ID",dataType="String",name="ID",example="1020332806740959233")String id;@ApiModelProperty(value="编码",dataType="String",name="code",example="001")@NotBlank(message = "编码不能为空")String code;@ApiModelProperty(value="名称",dataType="String",name="name",example="oKong")@NotBlank(message = "名称不能为空")String name;
}
Swagger访问与使用
api首页路径:http://127.0.0.1:8080/swagger-ui.html
**调试:**点击需要访问的api列表,点击try it out!
按钮,即可弹出一下页面:
执行:
结果:
大家可下载示例,查看自定义的字符出现的位置,这样可以对其有个大致了解,各字段的作用领域是哪里。
Swagger常用属性说明
| 作用范围 | API | 使用位置 | | --- | :-: | --: | | 对象属性 | @ApiModelProperty | 用在出入参数对象的字段上 | | 协议集描述 | @Api | 用于controller类上 | | 协议描述 | @ApiOperation | 用在controller的方法上 | | Response集 | @ApiResponses | 用在controller的方法上 | | Response | @ApiResponse | 用在 @ApiResponses里边 | | 非对象参数集 | @ApiImplicitParams | 用在controller的方法上 | | 非对象参数描述 | @ApiImplicitParam | 用在@ApiImplicitParams的方法里边 | | 描述返回对象的意义 | @ApiModel | 用在返回对象类上 |
常用的注解@Api
、@ApiOperation
、@ApiModel
、@ApiModelProperty
示例中有进行标注,对于其他注解,大家可自动谷歌,毕竟常用的就这几个了。有了swagger
之后,原本一些post
请求需要postman
这样的调试工具来进行发起,而现在直接在页面上就可以进行调试了,是不是很爽!对于服务的调用者而已,有了这份api文档也是一目了然,不需要和后端多少沟通成本,按着api说明进行前端开发即可。
总结
本章节主要是对
Swagger
的集成和简单使用进行了说明,详细的用法,可自行搜索相关资料下,这里就不阐述了。因为对于百分之八十之上的文档要求基本能满足了。一些比如前端根据swagger
的api-docs
进行前端的快速开发,这就需要实际情况实际约定了,比如快速的生成表单页等也是很方便的事情。最后,强烈建议在生产环境关闭swagger
,避免不必要的漏洞暴露!
最后
目前互联网上很多大佬都有
SpringBoot
系列教程,如有雷同,请多多包涵了。本文是作者在电脑前一字一句敲的,每一步都是实践的。若文中有所错误之处,还望提出,谢谢。
老生常谈
- 个人QQ:
499452441
- 微信公众号:
lqdevOps
个人博客:https://blog.lqdev.cn
完整示例:chapter-10
转载于:https://my.oschina.net/xiedeshou/blog/1860796
SpringBoot | 第十章:Swagger2的集成和使用相关推荐
- 基于Maven的Springboot+Mybatis+Druid+Swagger2+mybatis-generator框架环境搭建
首页 Android Java 服务器 标签云 作品 关于 赞助列表 <a href="https://github.com/RayeWang" class="f ...
- SpringBoot笔记:SpringBoot2.3集成SpringSession+nginx+redis实现session共享
文章目录 Spring Session介绍 Redis集成 yml配置 依赖添加 redis存值查看 登录服务器查看redis的值 查询所有"spring:session:"开头的 ...
- CAS学习笔记五:SpringBoot自动/手动配置方式集成CAS单点登出
本文目标 基于SpringBoot + Maven 分别使用自动配置与手动配置过滤器方式实现CAS客户端登出及单点登出. 本文基于<CAS学习笔记三:SpringBoot自动/手动配置方式集成C ...
- SpringBoot实战(八):集成Swagger
强烈推荐一个大神的人工智能的教程:http://www.captainbed.net/zhanghan [前言] 前后端分离是现在系统的主流,前端人员更多专注于前端功能,后端人员更加关注后端极大提高开 ...
- SpringBoot+Cloud+oauth2.0+JWT集成swagger及swagger-bootstrap-ui详细步骤
SpringBoot+Cloud集成swagger及swagger-bootstrap-ui详细步骤如下: 实现效果图 引入Maven依赖 swagger的配置文件属性 配置文件所需要的类 oauth ...
- 【SpringBoot框架篇】4.集成jta-atomikos实现分布式事务
文章目录 1.简介 1.1.分布式事务 1.2.JTA 1.3.atomikos 2.引入依赖 3.修改配置文件 4.添加配置读取类 5.创建多数据源,管理事务 6.数据持久化 7.数据库DLL文件 ...
- SpringBoot笔记:SpringBoot2.3集成Kafka组件配置
文章目录 说明 Springboot集成Kafka 依赖配置 配置文件yml配置 Producer生产者 Consumer消费者 测试代码 注意事项 说明 本文是接<Kafka学习:CentOS ...
- SpringBoot笔记:SpringBoot2.3集成Logback日志组件配置
文章目录 Logback简介 简介 日志级别 日志分类 Logback使用 添加依赖 配置Logback Logback参数解释 1.根节点configuration包含属性 2.根节点configu ...
- SpringBoot入门教程(十五)集成Druid
Druid是阿里巴巴开源平台上一个数据库连接池实现,它结合了C3P0.DBCP.PROXOOL等DB池的优点,同时加入了日志监控,可以很好的监控DB池连接和SQL的执行情况,可以说是针对监控而生的DB ...
- springboot quartz 动态配置_springboot集成quartz实现动态任务调度
quartz是一个开源的作业调度框架,本文就是介绍下springboot框架下继承quartz的一些使用示例 首先我们需要添加quartz的spring-boot-starter-quartz依赖 o ...
最新文章
- SAP MM MRP运行后触发的PR单据里没有Assign采购组织?
- idea代码调试debug篇
- Spring MVC RedirectAttributes的用法解决办法
- 辨别真假数据科学家必备手册:深度学习45个基础问题(附答案)
- Redis如何高效可靠地实现主从复制?终于有人讲明白了
- 抖音客新版UI短视频点赞任务系统完美运营级别[等级功能+信誉积分+保证金]
- 可以分屏的软件_Screen分屏软件下载|Screen+专业分屏 免费版v1.4.25 下载
- 实验3.2 定义一个简单的Computer类
- IHttpModule与IHttpHandler的区别整理
- matlab 矩阵除法计算,Matlab中的矩阵除法有问题???
- Python模块:生成随机数模块random
- 蓝桥杯 C语言 试题 基础练习 FJ的字符串
- java门基础学习(五)
- 个人看过的动漫、动画电影推荐
- BigWorld文件夹结构
- #7:怀念儿时的春节——9
- javaEE练习(商城练习)
- 618 大促运营必看!4 步教你玩转商品运营
- 电脑在线一键安装win10系统教程分享
- 条码标签编辑软件如何选择?
热门文章
- java课程讲解,Java基础教程详解:多线程(1)-----多线程概念
- 单片机c语言编程入门下載,51系列单片机C语言编程入门(下)
- mysql工厂模式_工厂模式IDAL详解
- dom定义了访问html文档对象的一套,HTML DOM基础知识(示例代码)
- python 控制流
- SQL分组字符串相连
- bash给脚本加进度条_shell脚本实现进度条
- slf4j打印未捕获异常信息_谁再悄咪咪的吃掉异常,我上去就是一 JIO
- 根据数据库名称glkf查看使用的用户
- 聊聊 Material Design 里,阴影的那些事儿!