【视频版】最新版Swagger 3升级指南和新功能体验!

作者 | 王磊

来源 | Java中文社群(ID:javacn666)

转载请联系授权(微信ID:GG_Stone)

Swagger 3.0 发布已经有一段时间了,它于 2020.7 月 发布,但目前市面上使用的主流版本还是 Swagger 2.X 版本和少量的 1.X 版本,然而作为一名合格的程序员怎么能不折腾新技术呢?所以本期就大家带来一篇最新版 Swagger 的内容,本文会带大家看最新版 Swagger 有哪些改变?又是如何将老版本 Swagger 升级到新版的?

Swagger 是什么?

Swagger 是一个用于生成、描述和调用 RESTful 接口的 Web 服务。通俗的来讲,Swagger 就是将项目中所有(想要暴露的)接口展现在页面上,并且可以进行接口调用和测试的服务。

PS:Swagger 遵循了 OpenAPI 规范,OpenAPI 是 Linux 基金会的一个项目,试图通过定义一种用来描述 API 格式或 API 定义的语言,来规范 RESTful 服务开发过程。

Swagger 官网地址:https://swagger.io/

Swagger 有什么用?

从上述 Swagger 定义我们不难看出 Swagger 有以下 3 个重要的作用:

  1. 将项目中所有的接口展现在页面上,这样后端程序员就不需要专门为前端使用者编写专门的接口文档;

  2. 当接口更新之后,只需要修改代码中的 Swagger 描述就可以实时生成新的接口文档了,从而规避了接口文档老旧不能使用的问题

  3. 通过 Swagger 页面,我们可以直接进行接口调用,降低了项目开发阶段的调试成本


Swagger 旧版本使用

Swagger 旧版本也就是目前市面上主流的 V2 版本是 Swagger 2.9.2,在讲新版本之前,我们先来回顾一下 Swagger 2.9.2 是如何使用的。

Swagger 2.9.2 的使用分为以下 4 步:

  1. 添加依赖

  2. 开启 Swagger 功能

  3. 配置 Swagger 文档摘要信息

  4. 调用接口访问

下面我们分别来看。

1.添加依赖

首先,我们要去 mvnrepository 查询 Swagger 的依赖,搜索“springfox”关键字,得到结果的前两条依赖信息,就是我们想要的结果,如下图所示:将这两个依赖添加带项目中:

<!-- 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>

为什么是“springfox”?

问:我们要使用的是 Swagger,为什么要搜索“springfox”?

答:Swagger 可以看作是一个遵循了 OpenAPI 规范的一项技术,而 springfox 则是这项技术的具体实现。就好比 Spring 中的 AOP 和 DI 一样,前者是思想,而后者是实现。

2.开启Swagger

在 Spring Boot 的启动类或配置类中添加 @EnableSwagger2 注释,开启 Swagger,部分核心代码如下:

@EnableSwagger2
@SpringBootApplication
public class Application {...

3.配置摘要信息

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;@Configuration
public class SwaggerConfig {@Beanpublic Docket createRestApi() {return new Docket(DocumentationType.SWAGGER_2) // 1.SWAGGER_2.select().apis(RequestHandlerSelectors.basePackage("com.example.swaggerv2.controller")) // 2.设置扫描路径.build();}
}

4.访问Swagger

项目正常启动之后使用“http://localhost:8080/swagger-ui.html”访问Swagger页面,如下图所示:

Swagger 最新版使用

Swagger 最新版的配置步骤和旧版本是一样,只是每个具体的配置项又略有不同,具体步骤如下。

1.添加依赖

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-boot-starter -->
<dependency><groupId>io.springfox</groupId><artifactId>springfox-boot-starter</artifactId><version>3.0.0</version>
</dependency>

从上述配置可以看出,Swagger 新版本的依赖项只有一个,而旧版本的依赖项有两个,相比来说也简洁了很多。

2.开启Swagger

在 Spring Boot 的启动类或配置类中添加 @EnableOpenApi 注释,开启 Swagger,部分核心代码如下:

@EnableOpenApi
@SpringBootApplication
public class Application {...

3.配置摘要信息

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.oas.annotations.EnableOpenApi;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;@Configuration
public class SwaggerConfig {@Beanpublic Docket createRestApi() {return new Docket(DocumentationType.OAS_30) // v2 不同.select().apis(RequestHandlerSelectors.basePackage("com.example.swaggerv3.controller")) // 设置扫描路径.build();}
}

从上述代码可以看出 Docket 的配置中只有文档的类型设置新老版本是不同的,新版本的配置是 OAS_30 而旧版本的配置是 SWAGGER_2

PS:OAS 是 OpenAPI Specification 的简称,翻译成中文就是 OpenAPI 说明书。

4.访问Swagger

新版本的 Swagger 访问地址和老版本的地址是不同的,新版版的访问地址是“localhost:8080/swagger-ui/”,如下图所示:

新版本 VS 老版本

新版本和老版本的区别主要体现在以下 4 个方面:

  1. 依赖项的添加不同:新版本只需要添加一项,而老版本需要添加两项;

  2. 启动 Swagger 的注解不同:新版本使用的是 @EnableOpenApi,而老版本是 @EnableSwagger2

  3. Docket(文档摘要信息)的文件类型配置不同:新版本配置的是 OAS_3,而老版本是 SWAGGER_2

  4. Swagger UI 访问地址不同:新版本访问地址是“http://localhost:8080/swagger-ui/”,而老版本访问地址是“http://localhost:8080/swagger-ui.html”。

总结

Swagger 新版本让人印象深刻的优点有两个:第一,配置变得简单了,比如依赖项配置减少了 50%,第二,新版 Swagger 页面设计风格有了不小的改变,新版的页面让人感觉更加现代化也更加具有科技感了,总体来说美观了不少。

值得一提的是 Swagger 的整个升级过程很平滑,从老版本升级到新版本,只需要简单的配置即可,那些用于描述接口的注解还是延续了老版本的用法,这样就可以在不修改大部分主要代码的情况下,可以成功到最新版本啦。

本文来自互联网用户投稿,该文观点仅代表作者本人,不代表本站立场。本站仅提供信息存储空间服务,不拥有所有权,不承担相关法律责任。如若转载,请注明出处:http://www.mzph.cn/news/544920.shtml

如若内容造成侵权/违法违规/事实不符,请联系多彩编程网进行投诉反馈email:809451989@qq.com,一经查实,立即删除!

相关文章

java treemap_Java TreeMap pollFirstEntry()方法与示例

java treemapTreeMap类pollFirstEntry()方法 (TreeMap Class pollFirstEntry() method) pollFirstEntry() method is available in java.util package. pollFirstEntry()方法在java.util包中可用。 pollFirstEntry() method is used to return and then remove the entry (key-…

各大厂面试高频的面试题新鲜出炉,你能答上几道?

关于生产环境如何配置线程数&#xff0c;还是要根据业务来进行区分&#xff0c;我们时常会听到什么IO密集型、CPU密集型任务...那么这里提一个问题&#xff1a;大家知道什么样的任务或者代码会被认定为IO/CPU密集&#xff1f;又是用什么样的标准来认定IO/CPU密集&#xff1f;如…

c/c++如何获取数组的长度

2019独角兽企业重金招聘Python工程师标准>>> C、C中没有提供 直接获取数组长度的函数&#xff0c;对于存放字符串的字符数组提供了一个strlen函数获取长度&#xff0c;那么对于其他类型的数组如何获取他们的长度呢&#xff1f;其中一种方法是使 用sizeof(array) / s…

JSP JAVA 自定义 错误页面(404,505,500)

当网站页面找不到或者服务器内部出错的时候&#xff0c;我们不想让用户看到默认的那张 404&#xff0c;500 的错误页面&#xff0c;那要是想自己做一张 找不到页面的页面改怎么做呢&#xff1f;在 web .xml 文件中 加入下面的语句就能达到这个效果<error-page><error-…

【送给读者】全新苹果 AirPods,包邮送一套!

为回馈长期以来科创人读者对本栏目的关注支持&#xff0c;本周小编联合了计算机领域八位高质量原创号主一起为大家送出一套 全新苹果AirPods 2代。以下推荐的公号原创率都很高&#xff0c;均为个人IP号&#xff0c;有些小伙伴应该已经关注部分公号。本次抽奖采用第三方抽奖小程…

java 方法 示例_Java扫描仪的hasNextBoolean()方法与示例

java 方法 示例扫描器类的hasNextBoolean()方法 (Scanner Class hasNextBoolean() method) hasNextBoolean() method is available in java.util package. hasNextBoolean()方法在java.util包中可用。 hasNextBoolean() method is used to check whether this Scanners next in…

进程控制(kill)

为什么80%的码农都做不了架构师&#xff1f;>>> kill&#xff1a;终止进程&#xff08;或传送信号到某进程&#xff09; kill [options] [process_ids] kill命令可以发送信号给进程&#xff0c;可以终止&#xff08;terminate&#xff09;&#xff08;默认操作&a…

oracle怎样修改表名、列名、字段类型、添加表列、删除表列

ALTER TABLE SCOTT.TEST RENAME TO TEST1--修改表名 ALTER TABLE SCOTT.TEST RENAME COLUMN NAME TO NAME1 --修改表列名 ALTER TABLE SCOTT.TEST MODIFY NAME1 NUMBER(20) --修改字段类型 ALTER TABLE SCOTT.TEST ADD ADDRESS VARCHAR2(40) --添加表列 ALTER TABLE SCOTT.TEST…

TextArea里Placeholder换行问题

转&#xff1a;http://www.tuicool.com/articles/feYVNf 页面上使用TextArea控件时&#xff0c;会时不时的想给个提示&#xff0c;比如按照一定方式操作之类的。 正常情况下&#xff0c;会使用Placeholder&#xff0c;但这样的提示是不会换行的&#xff0c;无论是用\r\n&…

printstream_Java PrintStream clearError()方法与示例

printstreamPrintStream类clearError()方法 (PrintStream Class clearError() method) clearError() method is available in java.io package. clearError()方法在java.io包中可用。 clearError() method is used to clear the internal error state of this PrintStream. cle…

uniq用法详解

uniquniq命令可以去除排序过的文件中的重复行&#xff0c;因此uniq经常和sort合用。也就是说&#xff0c;为了使uniq起作用&#xff0c;所有的重复行必须是相邻的。uniq语法[rootwww ~]# uniq [-icu]选项与参数&#xff1a;-i &#xff1a;忽略大小写字符的不同&#xff1b;-…

Swagger增强神器:Knife4j!用它轻松实现接口搜索、Word下载、接口过滤...

视频版内容&#xff1a;Swagger 是开发中最常用的框架之一了&#xff0c;但 Swagger 本身又有很多不完善的地方&#xff0c;比如&#xff0c;在众多的接口中查询某一个接口&#xff0c;又或者是把所有的接口导出成 Word 格式等&#xff0c;都无法在 Swagger 中实现。有人可能会…

tohexstring方法_Java Long类toHexString()方法的示例

tohexstring方法长类toHexString()方法 (Long class toHexString() method) toHexString() method is available in java.lang package. toHexString()方法在java.lang包中可用。 toHexString() method is used to represent a hexadecimal string of the given parameter [val…

关于显示和隐藏DIV标签

document.getElementById("DIV的ID").style.display"none";//隐藏 document.getElementById("DIV的ID").style.display"block";//显示

7种可能会导致内存泄漏的场景!

虽然Java程序员不用像C/C程序员那样时刻关注内存的使用情况&#xff0c;JVM会帮我们处理好这些&#xff0c;但并不是说有了GC就可以高枕无忧&#xff0c;内存泄露相关的问题一般在测试的时候很难发现&#xff0c;一旦上线流量起来可能马上就是一个诡异的线上故障。1. 内存泄露的…

logstash 过虑nginx访问日志

标题是不是可以翻译成这样&#xff1a;logstash Filters nginx access log好了&#xff0c;进入正题&#xff0c;日志管理服务器我用ElasticSearchLogStashKibanaRedis先说下我的架构&#xff1a;远程NGINX采集日志数据到REDISlogstashelasticsearchkibana服务器至于怎么部署&a…

java 方法 示例_Java语言环境getISOLanguages()方法与示例

java 方法 示例区域设置类getISOLanguages()方法 (Locale Class getISOLanguages() method) getISOLanguages() method is available in java.util package. getISOLanguages()方法在java.util包中可用。 getISOLanguages() method is used to return an array of string that …

struts2显示列表序号的办法

http://blog.knowsky.com/226680.htm 有的时候需要在页面上进行计算&#xff0c;比如要显示十条数据并且十条数据前要有显示123456……的序号&#xff0c;解决这个问题有两种办法。第一种是通过set标签实现&#xff1a; <s:set name"a" value1/> <s:ite…

Spring中的重试功能!嗯,有点东西

来源&#xff1a;https://albenw.github.io/posts/69a9647f/概要Spring实现了一套重试机制&#xff0c;功能简单实用。Spring Retry是从Spring Batch独立出来的一个功能&#xff0c;已经广泛应用于Spring Batch,Spring Integration, Spring for Apache Hadoop等Spring项目。 本…

关于Shell的一些常用命令

2019独角兽企业重金招聘Python工程师标准>>> ls -lat 列出当前目录所有东东的东东 ls -lath 人看的大小 ls -F | grep "/$"只搞目录 ls -lR 包括子目录… ls --ignore filename -lt 忽略某个 which&#xff0c;在PATH变量指定的路径中&#xff0c;搜索看某…