SpringBoot2 整合 Swagger2

SpringBoot整合三板斧

第一步、引入pom

  1. <dependency>
  2. <groupId>com.spring4all</groupId>
  3. <artifactId>swagger-spring-boot-starter</artifactId>
  4. <version>1.9.0.RELEASE</version>
  5. </dependency>
  6. <dependency>
  7. <groupId>com.github.xiaoymin</groupId>
  8. <artifactId>swagger-bootstrap-ui</artifactId>
  9. <version>1.9.6</version>
  10. </dependency>
  11. <dependency>
  12. <groupId>io.swagger</groupId>
  13. <artifactId>swagger-annotations</artifactId>
  14. <version>1.5.22</version>
  15. </dependency>
  16. <dependency>
  17. <groupId>io.swagger</groupId>
  18. <artifactId>swagger-models</artifactId>
  19. <version>1.5.22</version>
  20. </dependency>

swagger-spring-boot-starter该项目主要利用Spring Boot的自动化配置特性来实现快速的将swagger2引入spring boot应用来生成API文档,简化原生使用swagger2的整合代码。

swagger-bootstrap-uispringfox-swagger的增强UI实现,为Java开发者在使用Swagger的时候,能拥有一份简洁、强大的接口文档体验

swagger-annotations,swagger-models是因为springfox-swagger2包里有swagger-models-1.5.20.jar报错。所以替换成1.5.22版本

  1. java.lang.NumberFormatException: For input string: ""
  2. at java.lang.NumberFormatException.forInputString(NumberFormatException.java:65)
  3. at java.lang.Long.parseLong(Long.java:601)
  4. at java.lang.Long.valueOf(Long.java:803)
  5. at io.swagger.models.parameters.AbstractSerializableParameter.getExample(AbstractSerializableParameter.java:412)
  6. at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
  7. at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:62)
  8. at......

看下1.5.20版本里AbstractSerializableParameter.java源码:

  1. public Object getExample() {
  2. if (this.example == null) {
  3. return null;
  4. } else {
  5. try {
  6. if ("integer".equals(this.type)) {
  7. return Long.valueOf(this.example);
  8. }
  9. if ("number".equals(this.type)) {
  10. return Double.valueOf(this.example);
  11. }
  12. if ("boolean".equals(this.type) && ("true".equalsIgnoreCase(this.example) || "false".equalsIgnoreCase(this.defaultValue))) {
  13. return Boolean.valueOf(this.example);
  14. }
  15. } catch (NumberFormatException var2) {
  16. LOGGER.warn(String.format("Illegal DefaultValue %s for parameter type %s", this.defaultValue, this.type), var2);
  17. }
  18. return this.example;
  19. }
  20. }

这里只判断了this.example == null才返回null,其余会去进行转换,而空字符串也会进行转换,导致格式抛出格式化转换异常.再来看下1.5.22版本里AbstractSerializableParameter.java源码:

  1. public Object getExample() {
  2. if (this.example != null && !this.example.isEmpty()) {
  3. try {
  4. if ("integer".equals(this.type)) {
  5. return Long.valueOf(this.example);
  6. }
  7. if ("number".equals(this.type)) {
  8. return Double.valueOf(this.example);
  9. }
  10. if ("boolean".equals(this.type) && ("true".equalsIgnoreCase(this.example) || "false".equalsIgnoreCase(this.defaultValue))) {
  11. return Boolean.valueOf(this.example);
  12. }
  13. } catch (NumberFormatException var2) {
  14. LOGGER.warn(String.format("Illegal DefaultValue %s for parameter type %s", this.defaultValue, this.type), var2);
  15. }
  16. return this.example;
  17. } else {
  18. return this.example;
  19. }
  20. }

对example同时进行了null和空值的判断,官方也发现了自己的这个问题,我们进行相应的替换即可

第二部、配置

swagger-spring-boot-starter相关配置信息可参考如下地址:

swagger-bootstrap-ui相关配置信息可参考如下地址:

官方地址:https://doc.xiaominfo.com/guide/

swagger-bootstrap-ui目前已改名了knife4j-spring-boot-starter

项目正式更名为knife4j,取名knife4j是希望她能像一把匕首一样小巧,轻量,并且功能强悍,更名也是希望把她做成一个为Swagger接口文档服务的通用性解决方案,不仅仅只是专注于前端Ui前端.

swagger-bootstrap-ui的所有特性都会集中在knife4j-spring-ui包中,并且后续也会满足开发者更多的个性化需求.

  1. swagger:
  2. version: 1.0v # 版本号
  3. authorization: # 全局参数
  4. name: Authorization # 鉴权策略ID,对应 SecurityReferences ID
  5. type: ApiKey # 鉴权策略,可选 ApiKey | BasicAuth | None,默认ApiKey
  6. key-name: X-Token # 鉴权传递的Header参数
  7. # auth-regex: ^.*$ # 需要开启鉴权URL的正则, 默认^.*$匹配所有URL
  8. ui-config: # 排序规则
  9. operations-sorter: method # 按方法定义顺序排序
  10. tags-sorter: alpha # 按字母表排序
  11. docket: # 分组配置
  12. common:
  13. base-package: com.xxxx.a
  14. description: API接口文档
  15. title: xxx接口
  16. contact:
  17. name: xxx
  18. url: https://cn.bing.com/
  19. hq:
  20. base-package: com.xxxx.b
  21. description: API接口文档
  22. title: xxx接口
  23. contact:
  24. name: xxx
  25. url: https://zc.happyloves.cn:4443/wordpress/
  26. shop:
  27. base-package: com.xxxx.c
  28. description: API接口文档
  29. title: xxx接口
  30. contact:
  31. name: xxx
  32. url: https://zc.happyloves.cn

第三步、注解

  1. @EnableSwagger2Doc // 启用Swagger2
  2. @EnableSwaggerBootstrapUI //启用swagger-bootstrap-ui
  3. @SpringBootApplication
  4. public class WebApplication {
  5. public static void main(String[] args) {
  6. SpringApplication.run(WebApplication.class, args);
  7. }
  8. }

编写代码

  1. @Api(value = "DemoOne-DemoOne服务~~~~~~~~", tags = {"1-DemoOne-DemoOne服务"})
  2. @Slf4j
  3. @Validated
  4. @RestController
  5. @RequestMapping("/common/DemoOne")
  6. public class DemoOneController {
  7. private final DemoOneService service;
  8. @Autowired
  9. public DemoOneController(DemoOneService service) {
  10. this.service = service;
  11. }
  12. //=====================================================================================DELETE=====================================================================================
  13. @ApiOperation(value = "根据主键ID删除", notes = "根据主键ID删除~~~~~~~~~~~~~")
  14. @DeleteMapping("/{id}")
  15. public ApiMessage deleteById(@PathVariable @Min(1) int id) throws Exception {
  16. return service.deleteById(id);
  17. }
  18. //=====================================================================================GET========================================================================================
  19. @ApiOperation(value = "获取所有数据", notes = "获取所有数据~~~~~~~~~~~~~")
  20. @GetMapping("/")
  21. public ApiMessage<List<DemoOneResponse>> getAllList() {
  22. return service.getAllList();
  23. }
  24. @ApiOperation(value = "根据主键ID获取数据", notes = "根据主键ID获取数据~~~~~~~~~~~~~")
  25. @ApiImplicitParams(value = {
  26. @ApiImplicitParam(name = "id", required = true, value = "主键ID", paramType = "path", dataType = "string"),
  27. })
  28. @GetMapping("/{id}/{name}")
  29. public ApiMessage<DemoOneResponse> getById(@PathVariable @Min(1) int id, @PathVariable @AssertFalse boolean name) {
  30. return service.getById(id);
  31. }
  32. //=====================================================================================POST=======================================================================================
  33. @ApiOperation(value = "新增DemoOne数据", notes = "新增DemoOne数据~~~~~~~~~~~~~")
  34. @PostMapping("/")
  35. public ApiMessage<DemoOneResponse> save(@RequestBody @Valid DemoOneRequest parameter) {
  36. return service.addDemoOne(parameter);
  37. }
  38. //=====================================================================================PUT========================================================================================
  39. @ApiOperation(value = "更新DemoOne数据", notes = "更新DemoOne数据~~~~~~~~~~~~~")
  40. @PutMapping("/")
  41. public ApiMessage<DemoOneResponse> update(@RequestBody @Valid DemoOneRequest parameter) {
  42. return service.update(parameter);
  43. }

大功告成!!!启动访问如下地址:

Swagger2地址:

http://${ip地址}

SpringBoot2 整合 Swagger2的更多相关文章

  1. SpringBoot2 整合 Swagger2文档 使用BootstrapUI页面

    SpringBoot2 整合 Swagger2 SpringBoot整合三板斧 第一步.引入pom <dependency> <groupId>com.spring4all&l ...

  2. SpringBoot2 整合Kafka组件,应用案例和流程详解

    本文源码:GitHub·点这里 || GitEE·点这里 一.搭建Kafka环境 1.下载解压 -- 下载 wget http://mirror.bit.edu.cn/apache/kafka/2.2 ...

  3. Springboot项目整合Swagger2报错

    SpringBoot2.2.6整合swagger2.2.2版本的问题,启动SpringBoot报如下错: Error starting ApplicationContext. To display t ...

  4. SpringBoot整合Swagger2,再也不用维护接口文档了!

    前后端分离后,维护接口文档基本上是必不可少的工作.一个理想的状态是设计好后,接口文档发给前端和后端,大伙按照既定的规则各自开发,开发好了对接上了就可以上线了.当然这是一种非常理想的状态,实际开发中却很 ...

  5. springBoot(12)---整合Swagger2

    Spingboot整合Swagger2 随着互联网技术的发展,一般开发都是前后端分离,那么前端和后端的唯一联系,变成了API接口:API文档变成了前后端开发人员联系的纽带,变得越来越重要,没有API ...

  6. SpringBoot整合系列-整合Swagger2

    原创作品,可以转载,但是请标注出处地址:https://www.cnblogs.com/V1haoge/p/9959844.html SpringBoot整合Swagger2 步骤 第一步:添加必要的 ...

  7. SpringBoot(七):SpringBoot整合Swagger2

    原文地址:https://blog.csdn.net/saytime/article/details/74937664 手写Api文档的几个痛点: 文档需要更新的时候,需要再次发送一份给前端,也就是文 ...

  8. SpringBoot整合Swagger2

    相信各位在公司写API文档数量应该不少,当然如果你还处在自己一个人开发前后台的年代,当我没说,如今为了前后台更好的对接,还是为了以后交接方便,都有要求写API文档. 手写Api文档的几个痛点: 文档需 ...

  9. springboot+cloud 学习(四)Zuul整合Swagger2

    前言 在微服务架构下,服务是分散的,怎么把所有服务接口整合到一起是我们需要关注的. 下面举例用zuul作为分布式系统的网关,同时使用swagger生成文档,想把整个系统的文档整合在同一个页面上来说明. ...

随机推荐

  1. CentOS7使用firewalld管理防火墙与端口

    firewalld的基本使用 启动: systemctl start firewalld 关闭: systemctl stop firewalld 查看状态: systemctl status fir ...

  2. ActiveMQ此例简单介绍基于docker的activemq安装与集群搭建

    ActiveMQ拓展连接 此例简单介绍基于Docker的activemq安装与集群搭建 一 :安装 1.获取activemq镜像 docker pull webcenter/activemq 2.启动 ...

  3. 安装NSQ

    安装文档 https://nsq.io/deployment/installing.html 打开连接后,根据系统找到对应的二进制包 一般都是linux则下载 https://s3.amazonaws ...

  4. 本地开启https服务

    ### ##自签名证书 ##配置Apache服务器SSL ##自己作为CA签发证书 ###这里是OpenSSL和HTTPS的介绍 OpenSSL HTTPS 开启HTTPS配置前提是已在Mac上搭建A ...

  5. GeoMesa-单机搭建

    系统安装 CentOS部署 新建虚拟电脑 类型:Linux 版本:Red Hat(64-bit) 创建虚拟硬盘 [x] 动态分配(磁盘占用较小) [ ] 固定大小(使用起来较快) 安装设置(设置roo ...

  6. 从社交到IP 庞大手游玩家大军迈向社群化之路

    庞大手游玩家大军迈向社群化之路" title="从社交到IP 庞大手游玩家大军迈向社群化之路"> 移动互联网及相关智能设备的快速迭进,不仅改变了我们的生活方式,也彻 ...

  7. Autotestplat.com 更新了!

    1 提供测试发帖留言功能 2 自动化平台体验功能 3 提供招聘资讯功能       4 提供推荐书籍功能

  8. React使用笔记2--创建登录组件

    文章目录 最近在学习使用React作为前端的框架,<React使用笔记>系列用于记录过程中的一些使用和解决方法.本文记录搭建登录页面的过程. 根据产品规划划分模块 主要页面逻辑 在这里,本 ...

  9. 什么是SNAT

    SNAT是源地址转换,其作用是将ip数据包的源地址转换成另外一个地址,可能有人觉得奇怪,好好的为什么要进行ip地址转换啊,为了弄懂这个问题,我们要看一下局域网用户上公网的原理,假设内网主机A(192. ...

  10. LeetCode~1033.移动石子直到连续

    1033.移动石子直到连续 三枚石子放置在数轴上,位置分别为 a,b,c. 每一回合,我们假设这三枚石子当前分别位于位置 x, y, z 且 x < y < z.从位置 x 或者是位置 z ...