SpringBoot2 整合 Swagger2

SpringBoot2 整合 Swagger2

SpringBoot整合三板斧

第一步、引入pom

<dependency>
  <groupId>com.spring4all</groupId>
  <artifactId>swagger-spring-boot-starter</artifactId>
  <version>1.9.0.RELEASE</version>
</dependency>
<dependency>
  <groupId>com.github.xiaoymin</groupId>
  <artifactId>swagger-bootstrap-ui</artifactId>
  <version>1.9.6</version>
</dependency>

<dependency>
  <groupId>io.swagger</groupId>
  <artifactId>swagger-annotations</artifactId>
  <version>1.5.22</version>
</dependency>
<dependency>
  <groupId>io.swagger</groupId>
  <artifactId>swagger-models</artifactId>
  <version>1.5.22</version>
</dependency>

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

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

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

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

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

public Object getExample() {
    if (this.example == null) {
        return null;
    } else {
        try {
            if ("integer".equals(this.type)) {
                return Long.valueOf(this.example);
            }

            if ("number".equals(this.type)) {
                return Double.valueOf(this.example);
            }

            if ("boolean".equals(this.type) && ("true".equalsIgnoreCase(this.example) || "false".equalsIgnoreCase(this.defaultValue))) {
                return Boolean.valueOf(this.example);
            }
        } catch (NumberFormatException var2) {
            LOGGER.warn(String.format("Illegal DefaultValue %s for parameter type %s", this.defaultValue, this.type), var2);
        }

        return this.example;
    }
}

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

public Object getExample() {
    if (this.example != null && !this.example.isEmpty()) {
        try {
            if ("integer".equals(this.type)) {
                return Long.valueOf(this.example);
            }

            if ("number".equals(this.type)) {
                return Double.valueOf(this.example);
            }

            if ("boolean".equals(this.type) && ("true".equalsIgnoreCase(this.example) || "false".equalsIgnoreCase(this.defaultValue))) {
                return Boolean.valueOf(this.example);
            }
        } catch (NumberFormatException var2) {
            LOGGER.warn(String.format("Illegal DefaultValue %s for parameter type %s", this.defaultValue, this.type), var2);
        }

        return this.example;
    } else {
        return this.example;
    }
}

对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包中,并且后续也会满足开发者更多的个性化需求.

swagger:
  version: 1.0v # 版本号
  authorization: # 全局参数
    name: Authorization # 鉴权策略ID，对应 SecurityReferences ID
    type: ApiKey # 鉴权策略，可选 ApiKey | BasicAuth | None，默认ApiKey
    key-name: X-Token # 鉴权传递的Header参数
  #    auth-regex: ^.*$ # 需要开启鉴权URL的正则, 默认^.*$匹配所有URL
  ui-config: # 排序规则
    operations-sorter: method # 按方法定义顺序排序
    tags-sorter: alpha # 按字母表排序
  docket: # 分组配置
    common:
      base-package: com.xxxx.a
      description: API接口文档
      title: xxx接口
      contact:
        name: xxx
        url: https://cn.bing.com/
    hq:
      base-package: com.xxxx.b
      description: API接口文档
      title: xxx接口
      contact:
        name: xxx
        url: https://zc.happyloves.cn:4443/wordpress/
    shop:
      base-package: com.xxxx.c
      description: API接口文档
      title: xxx接口
      contact:
        name: xxx
        url: https://zc.happyloves.cn

第三步、注解

@EnableSwagger2Doc // 启用Swagger2
@EnableSwaggerBootstrapUI //启用swagger-bootstrap-ui
@SpringBootApplication
public class WebApplication {
    public static void main(String[] args) {
        SpringApplication.run(WebApplication.class, args);
    }
}

编写代码

@Api(value = "DemoOne-DemoOne服务~~~~~~~~", tags = {"1-DemoOne-DemoOne服务"})
@Slf4j
@Validated
@RestController
@RequestMapping("/common/DemoOne")
public class DemoOneController {
    private final DemoOneService service;

    @Autowired
    public DemoOneController(DemoOneService service) {
        this.service = service;
    }

    //=====================================================================================DELETE=====================================================================================
    @ApiOperation(value = "根据主键ID删除", notes = "根据主键ID删除~~~~~~~~~~~~~")
    @DeleteMapping("/{id}")
    public ApiMessage deleteById(@PathVariable @Min(1) int id) throws Exception {
        return service.deleteById(id);
    }

    //=====================================================================================GET========================================================================================

    @ApiOperation(value = "获取所有数据", notes = "获取所有数据~~~~~~~~~~~~~")
    @GetMapping("/")
    public ApiMessage<List<DemoOneResponse>> getAllList() {
        return service.getAllList();
    }

    @ApiOperation(value = "根据主键ID获取数据", notes = "根据主键ID获取数据~~~~~~~~~~~~~")
    @ApiImplicitParams(value = {
            @ApiImplicitParam(name = "id", required = true, value = "主键ID", paramType = "path", dataType = "string"),
    })
    @GetMapping("/{id}/{name}")
    public ApiMessage<DemoOneResponse> getById(@PathVariable @Min(1) int id, @PathVariable @AssertFalse boolean name) {
        return service.getById(id);
    }

    //=====================================================================================POST=======================================================================================
    @ApiOperation(value = "新增DemoOne数据", notes = "新增DemoOne数据~~~~~~~~~~~~~")
    @PostMapping("/")
    public ApiMessage<DemoOneResponse> save(@RequestBody @Valid DemoOneRequest parameter) {
        return service.addDemoOne(parameter);
    }

    //=====================================================================================PUT========================================================================================
    @ApiOperation(value = "更新DemoOne数据", notes = "更新DemoOne数据~~~~~~~~~~~~~")
    @PutMapping("/")
    public ApiMessage<DemoOneResponse> update(@RequestBody @Valid DemoOneRequest parameter) {
        return service.update(parameter);
    }

大功告成！！！启动访问如下地址：

Swagger2地址：

http://${ip地址}??{端口}/swagger-ui.html

swagger-bootstrap-ui地址：

http://${ip地址}??{端口}/doc.html

赵小胖个人博客

原文地址：https://www.cnblogs.com/Sky0914/p/12589396.html

时间： 2024-10-07 15:22:53

SpringBoot2 整合 Swagger2的相关文章

SpringBoot2 整合Kafka组件，应用案例和流程详解

本文源码:GitHub·点这里 || GitEE·点这里 一.搭建Kafka环境 1.下载解压 -- 下载 wget http://mirror.bit.edu.cn/apache/kafka/2.2.0/kafka_2.11-2.2.0.tgz -- 解压 tar -zxvf kafka_2.11-2.2.0.tgz -- 重命名 mv kafka_2.11-2.2.0 kafka2.11 2.启动Kafka服务 kafka依赖ZooKeeper服务,需要本地安装并启动ZooKeeper. 参

Swagger2 常用使用 及 SpringBoo 整合 Swagger2

手写Api文档的几个痛点: 文档需要更新的时候,需要再次发送一份给前端,也就是文档更新交流不及时. 接口返回结果不明确 不能直接在线测试接口,通常需要使用工具,比如postman 接口文档太多,不好管理 Swagger也就是为了解决这个问题,当然也不能说Swagger就一定是完美的,当然也有缺点,最明显的就是代码移入性比较强. 这里讲解的是SpringBoot整合Swagger2,直接生成接口文档的方式. 一.依赖 <dependency> <groupId>io.springfo

5分钟 springboot 整合swagger2

springboot 整合swagger2 1.maven配置文件中添加依赖 <properties> <swagger2.version>2.2.2</swagger2.version> </properties> -------------------------------------------------- <dependency> <groupId>io.springfox</groupId> <arti

SpringBoot整合Swagger2

手写Api文档的几个痛点: 文档需要更新的时候,需要再次发送一份给前端,也就是文档更新交流不及时. 接口返回结果不明确 不能直接在线测试接口,通常需要使用工具,比如postman 接口文档太多,不好管理 Swagger也就是为了解决这个问题,当然也不能说Swagger就一定是完美的,当然也有缺点,最明显的就是代码移入性比较强. 其他的不多说,想要了解Swagger的,可以去Swagger官网,可以直接使用Swagger editor编写接口文档,当然我们这里讲解的是SpringBoot整合Swa

Spring Boot2 系列教程(十七)SpringBoot 整合 Swagger2

前后端分离后,维护接口文档基本上是必不可少的工作. 一个理想的状态是设计好后,接口文档发给前端和后端,大伙按照既定的规则各自开发,开发好了对接上了就可以上线了.当然这是一种非常理想的状态,实际开发中却很少遇到这样的情况,接口总是在不断的变化之中,有变化就要去维护,做过的小伙伴都知道这件事有多么头大!还好,有一些工具可以减轻我们的工作量,Swagger2 就是其中之一,至于其他类似功能但是却收费的软件,这里就不做过多介绍了.本文主要和大伙来聊下 在Spring Boot 中如何整合 Swagger

SpringBoot2 整合 Zookeeper组件，管理架构中服务协调

本文源码:GitHub·点这里 || GitEE·点这里 一.Zookeeper基础简介 1.概念简介 Zookeeper是一个Apache开源的分布式的应用,为系统架构提供协调服务.从设计模式角度来审视:该组件是一个基于观察者模式设计的框架,负责存储和管理数据,接受观察者的注册,一旦数据的状态发生变化,Zookeeper就将负责通知已经在Zookeeper上注册的观察者做出相应的反应,从而实现集群中类似Master/Slave管理模式.ZooKeeper的目标就是封装好复杂易出错的关键服务,将

SpringBoot2 整合Nacos组件，环境搭建和入门案例详解

摘自:https://www.cnblogs.com/cicada-smile/p/12190192.html 本文源码:GitHub·点这里 || GitEE·点这里 一.Nacos基础简介 1.概念简介 Nacos 是构建以“服务”为中心的现代应用架构,如微服务范式.云原生范式等服务基础设施.聚焦于发现.配置和管理微服务.Nacos提供一组简单易用的特性集,帮助开发者快速实现动态服务发现.服务配置.服务元数据及流量管理.敏捷构建.交付和管理微服务平台. 2.关键特性 动态配置服务 服务发现和

SpirngBoot之整合Swagger2

前言 swagger,中文"拽"的意思.它是一个功能强大的api框架,它的集成非常简单,不仅提供了在线文档的查阅, 而且还提供了在线文档的测试.另外swagger很容易构建restful风格的api. 一.Swagger概述 Swagger是一组围绕OpenAPI规范构建的开源工具,可帮助设计.构建.记录和使用REST API. 简单说下,它的出现就是为了方便进行测试后台的restful形式的接口,实现动态的更新,当我们在后台的接口 修改了后,swagger可以实现自动的更新,而不需要

Spring Mvc和SpringBoot整合Swagger2

各位同学大家好,最近项目赶进度,没有钻研技术的时间,但碰巧今天需要在Spring项目上进行SpringMvc和Swagger的整合,而第一次使用Swagger是在SpringBoot项目上,因此踩了不少的坑,于是想和大家分享一下 :关于Swagger在SpringBoot或者和SpringMvc的集成! 随着开发模式逐渐向前后端分离演变,沟通的成本逐渐增加,前端和后端的唯一联系,变成了API接口:API文档变成了前后端开发人员联系的纽带,变得越来越重要,swagger就是一款让你更好的书写API