前言

前一章节介绍了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; @Bean
public 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 { @Autowired
IUserService 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的集成和简单使用进行了说明,详细的用法,可自行搜索相关资料下,这里就不阐述了。因为对于百分之八十之上的文档要求基本能满足了。一些比如前端根据swaggerapi-docs进行前端的快速开发,这就需要实际情况实际约定了,比如快速的生成表单页等也是很方便的事情。最后,强烈建议在生产环境关闭swagger,避免不必要的漏洞暴露!

最后

目前互联网上很多大佬都有SpringBoot系列教程,如有雷同,请多多包涵了。本文是作者在电脑前一字一句敲的,每一步都是实践的。若文中有所错误之处,还望提出,谢谢。

老生常谈

  • 个人QQ:499452441
  • 微信公众号:lqdevOps

个人博客:https://blog.lqdev.cn

完整示例:chapter-10

原文地址:http://blog.lqdev.cn/2018/07/21/springboot/chapter-ten/

SpringBoot | 第十章:Swagger2的集成和使用的更多相关文章

  1. springboot与swagger2的集成

    springboot与swagger2的集成 1.出现的背景 随着互联网技术的发展,现在的网站架构基本都由原来的后端渲染变成了:前端渲染.先后端分离的形态,而前端和后端的唯一联系,变成了API接口: ...

  2. Springboot+swagger2.7集成开发

    Springboot+swagger2.7集成开发 本篇文章是介绍最新的springboot和swagger2.7集成开发和2.0稍微有一些出入: Springboot集成环境配置 Swagger2. ...

  3. 基于Maven的Springboot+Mybatis+Druid+Swagger2+mybatis-generator框架环境搭建

    基于Maven的Springboot+Mybatis+Druid+Swagger2+mybatis-generator框架环境搭建 前言 最近做回后台开发,重新抓起以前学过的SSM(Spring+Sp ...

  4. Springboot系列(七) 集成接口文档swagger,使用,测试

    Springboot 配置接口文档swagger 往期推荐 SpringBoot系列(一)idea新建Springboot项目 SpringBoot系列(二)入门知识 springBoot系列(三)配 ...

  5. SpringBoot中Shiro使用Pac4j集成CAS认证

    SpringBoot中Shiro使用Pac4j集成CAS认证 Pac4j 简介 Pac4j与Shiro,Spring Security一样都是权限框架,并且提供了OAuth - SAML - CAS ...

  6. SpringBoot系列(六)集成thymeleaf详解版

    SpringBoot系列(六)集成thymeleaf详解版 1. thymeleaf简介  1. Thymeleaf是适用于Web和独立环境的现代服务器端Java模板引擎.  2. Thymeleaf ...

  7. CAS学习笔记五:SpringBoot自动/手动配置方式集成CAS单点登出

    本文目标 基于SpringBoot + Maven 分别使用自动配置与手动配置过滤器方式实现CAS客户端登出及单点登出. 本文基于<CAS学习笔记三:SpringBoot自动/手动配置方式集成C ...

  8. 微服务学习二:springboot与swagger2的集成

    现在测试都提倡自动化测试,那我们作为后台的开发人员,也得进步下啊,以前用postman来测试后台接口,那个麻烦啊,一个字母输错就导致测试失败,现在swagger的出现可谓是拯救了这些开发人员,便捷之处 ...

  9. 微服务:springboot与swagger2的集成

    现在测试都提倡自动化测试,那我们作为后台的开发人员,也得进步下啊,以前用postman来测试后台接口,那个麻烦啊,一个字母输错就导致测试失败,现在swagger的出现可谓是拯救了这些开发人员,便捷之处 ...

随机推荐

  1. 三 akka学习 actor的例子

    (转载: http://blog.csdn.net/chenleixing/article/details/44044243 ) Java并发编程的4种风格:Threads,Executors,For ...

  2. ES6学习之字符串的扩展

    字符的Unicode表示法 \uxxxx可以表示一个双字节的字符(xxxx表示字符编码,范围在0000---FFFF),超出此范围用两个双字节表示. console.log("\u0061& ...

  3. python 基础 列表 增删改查

    names = ["aaron", "alex", "james", "meihengfan"]names2 = [1, ...

  4. linux日常管理-xarge_exec

    在find搜索到文件之后再进行操作 exec是find的一个选项. {}表示前面搜索到的结果,\:是exec特殊的用法. xarge拥有同样的功能,需用选项 -i 可以用在其他命令的后面

  5. 如何从光盘本地安装CentOS 7图形界面(Gnome GUI)

    本例中通过在CentOS 7中修改repo文件,直接从光盘或者ISO镜像文件安装Gnome图形界面(Gnome GUI),从而避免耗时从官网或镜像下载. 1.首先确保光盘或者ISO镜像文件正确连接到客 ...

  6. ObjectInputStream缓存数据

    DataManager /** * 本地数据的存储 * @author Administrator * */ public class DataManager { private static fin ...

  7. 关于android 数据库查询出现 _id column do not exist 的处理

    查询的字段必须带上_id字段,否则就会出现此类异常,导致程序崩溃

  8. C++经典题目:有n个整数,使前面各数顺序向后移动m个位置

    问题描述: 有n个整数,使前面各数顺序向后移动m个位置,最后m个数变成最前m个数. 程序代码: #include<iostream> #define MAXLEN 200 using na ...

  9. 我的笔记文档版本控制系统-MediaWiki-安装/基本设置

    如果你一直想要一个可以进行版本控制的文档存储工具,那MediaWiki是一个不错的选择.也许,用版本控制来描述MediaWiki有点不妥,但它对于我来说就是如此了.我会将学习笔记都记录在MediaWi ...

  10. hdu1085

    #include <iostream> #include <cstring> using namespace std; int n[3],a[9000],b[9000],i,j ...