来源 | Java中文社群(ID:javacn666)转载请联系授权(微信ID:GG_Stone)
Swagger 3.0 发布已经有一段时间了,它于 2020.7 月 发布,但目前市面上使用的主流版本还是 Swagger 2.X 版本和少量的 1.X 版本,然而作为一名合格的程序员怎么能不折腾新技术呢?所以本期就大家带来一篇最新版 Swagger 的内容,本文会带大家看最新版 Swagger 有哪些改变?又是如何将老版本 Swagger 升级到新版的?
Swagger 是一个用于生成、描述和调用 RESTful 接口的 Web 服务。通俗的来讲,Swagger 就是将项目中所有(想要暴露的)接口展现在页面上,并且可以进行接口调用和测试的服务。
Swagger 官网地址:https://swagger.io/
从上述 Swagger 定义我们不难看出 Swagger 有以下 3 个重要的作用:
将项目中所有的接口展现在页面上,这样后端程序员就不需要专门为前端使用者编写专门的接口文档;
当接口更新之后,只需要修改代码中的 Swagger 描述就可以实时生成新的接口文档了,从而规避了接口文档老旧不能使用的问题;
通过 Swagger 页面,我们可以直接进行接口调用,降低了项目开发阶段的调试成本。
Swagger 旧版本也就是目前市面上主流的 V2 版本是 Swagger 2.9.2,在讲新版本之前,我们先来回顾一下 Swagger 2.9.2 是如何使用的。
Swagger 2.9.2 的使用分为以下 4 步:
下面我们分别来看。
首先,我们要去 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>
问:我们要使用的是 Swagger,为什么要搜索“springfox”?
答:Swagger 可以看作是一个遵循了 OpenAPI 规范的一项技术,而 springfox 则是这项技术的具体实现。就好比 Spring 中的 AOP 和 DI 一样,前者是思想,而后者是实现。
在 Spring Boot 的启动类或配置类中添加 @EnableSwagger2 注释,开启 Swagger,部分核心代码如下:
- @EnableSwagger2
- @SpringBootApplication
- public class Application {...
- 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 {
- @Bean
- public Docket createRestApi() {
- return new Docket(DocumentationType.SWAGGER_2) // 1.SWAGGER_2
- .select()
- .apis(RequestHandlerSelectors.basePackage("com.example.swaggerv2.controller")) // 2.设置扫描路径
- .build();
- }
- }
项目正常启动之后使用“http://localhost:8080/swagger-ui.html”访问Swagger页面,如下图所示:
Swagger 最新版的配置步骤和旧版本是一样,只是每个具体的配置项又略有不同,具体步骤如下。
- <!-- 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 新版本的依赖项只有一个,而旧版本的依赖项有两个,相比来说也简洁了很多。
在 Spring Boot 的启动类或配置类中添加 @EnableOpenApi 注释,开启 Swagger,部分核心代码如下:
- @EnableOpenApi
- @SpringBootApplication
- public class Application {...
- 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 {
- @Bean
- public Docket createRestApi() {
- return new Docket(DocumentationType.OAS_30) // v2 不同
- .select()
- .apis(RequestHandlerSelectors.basePackage("com.example.swaggerv3.controller")) // 设置扫描路径
- .build();
- }
- }
从上述代码可以看出 Docket 的配置中只有文档的类型设置新老版本是不同的,新版本的配置是 OAS_30 而旧版本的配置是 SWAGGER_2。
新版本的 Swagger 访问地址和老版本的地址是不同的,新版版的访问地址是“localhost:8080/swagger-ui/”,如下图所示:
新版本和老版本的区别主要体现在以下 4 个方面:
Swagger 新版本让人印象深刻的优点有两个:第一,配置变得简单了,比如依赖项配置减少了 50%,第二,新版 Swagger 页面设计风格有了不小的改变,新版的页面让人感觉更加现代化也更加具有科技感了,总体来说美观了不少。
值得一提的是 Swagger 的整个升级过程很平滑,从老版本升级到新版本,只需要简单的配置即可,那些用于描述接口的注解还是延续了老版本的用法,这样就可以在不修改大部分主要代码的情况下,可以成功到最新版本啦。
目标 在仿真理论中,生成随机变量是最重要的构建块之一,而这些随机变量大多是由...
文章已收录Github精选,欢迎Star: https://github.com/yehongzhi/learningSumma...
2020年注定是个不平凡的一年,新冠肺炎疫情全球蔓延,对全球经济发展、科技进步...
公司网站 域名 空间多少钱?公司搭 建网站 缺少不了域名和空间,具体需要多少钱...
3月8日消息,据外媒报道,物联网研究机构IoTAnalytics称,三分之一的制造商正计...
域名 过期多少天可以注册?域名过期大概60天以后会被注册局删除,删除之后就可以...
A公司在华为云中购买了多种资源,公司中有多个职能团队,这些职能团队需要使用一...
1.现在赶作业是一种时尚,所以我很赶得上潮流。 2.我房间里堆满了情人节卡片,...
1.话费没了,流量没了,短信没了,寒假没了,作业还有。 2.别紧张,我又不是什么...
如果当前云服务器系统盘容量不能满足您的存储需要,您可以在购买了云服务器之后...