文章详情

短信预约-IT技能 免费直播动态提醒

请输入下面的图形验证码

提交验证

短信预约提醒成功

最新版Swagger 3升级指南和新功能体验!

2024-12-03 09:26

关注

来源 | Java中文社群(ID:javacn666)转载请联系授权(微信ID:GG_Stone)

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

Swagger 是什么?

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

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

Swagger 有什么用?

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

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

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

通过 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”关键字,得到结果的前两条依赖信息,就是我们想要的结果,如下图所示:


将这两个依赖添加带项目中:

  1. -- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 --> 
  2.  
  3.     io.springfox 
  4.     springfox-swagger2 
  5.     2.9.2 
  6.  
  7.  
  8. -- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui --> 
  9.  
  10.     io.springfox 
  11.     springfox-swagger-ui 
  12.     2.9.2 
  13.  

为什么是“springfox”?

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

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

2.开启Swagger

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

  1. @EnableSwagger2 
  2. @SpringBootApplication 
  3. public class Application {... 

3.配置摘要信息

  1. import org.springframework.context.annotation.Bean; 
  2. import org.springframework.context.annotation.Configuration; 
  3. import springfox.documentation.builders.RequestHandlerSelectors; 
  4. import springfox.documentation.spi.DocumentationType; 
  5. import springfox.documentation.spring.web.plugins.Docket; 
  6. import springfox.documentation.swagger2.annotations.EnableSwagger2; 
  7.  
  8. @Configuration 
  9. public class SwaggerConfig { 
  10.     @Bean 
  11.     public Docket createRestApi() { 
  12.         return new Docket(DocumentationType.SWAGGER_2) // 1.SWAGGER_2 
  13.                 .select() 
  14.                 .apis(RequestHandlerSelectors.basePackage("com.example.swaggerv2.controller")) // 2.设置扫描路径 
  15.                 .build(); 
  16.     } 

4.访问Swagger

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

 

Swagger 最新版使用

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

1.添加依赖

  1. -- https://mvnrepository.com/artifact/io.springfox/springfox-boot-starter --> 
  2.  
  3.   io.springfox 
  4.   springfox-boot-starter 
  5.   3.0.0 
  6.  

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

2.开启Swagger

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

  1. @EnableOpenApi 
  2. @SpringBootApplication 
  3. public class Application {... 

3.配置摘要信息

  1. import org.springframework.context.annotation.Bean; 
  2. import org.springframework.context.annotation.Configuration; 
  3. import springfox.documentation.builders.RequestHandlerSelectors; 
  4. import springfox.documentation.oas.annotations.EnableOpenApi; 
  5. import springfox.documentation.spi.DocumentationType; 
  6. import springfox.documentation.spring.web.plugins.Docket; 
  7.  
  8. @Configuration 
  9. public class SwaggerConfig { 
  10.     @Bean 
  11.     public Docket createRestApi() { 
  12.         return new Docket(DocumentationType.OAS_30) // v2 不同 
  13.                 .select() 
  14.                 .apis(RequestHandlerSelectors.basePackage("com.example.swaggerv3.controller")) // 设置扫描路径 
  15.                 .build(); 
  16.     } 

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

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

 

来源: Java中文社群内容投诉

免责声明:

① 本站未注明“稿件来源”的信息均来自网络整理。其文字、图片和音视频稿件的所属权归原作者所有。本站收集整理出于非商业性的教育和科研之目的,并不意味着本站赞同其观点或证实其内容的真实性。仅作为临时的测试数据,供内部测试之用。本站并未授权任何人以任何方式主动获取本站任何信息。

② 本站未注明“稿件来源”的临时测试数据将在测试完成后最终做删除处理。有问题或投稿请发送至: 邮箱/279061341@qq.com QQ/279061341

软考中级精品资料免费领

  • 历年真题答案解析
  • 备考技巧名师总结
  • 高频考点精准押题
  • 2024年上半年信息系统项目管理师第二批次真题及答案解析(完整版)

    难度     813人已做
    查看
  • 【考后总结】2024年5月26日信息系统项目管理师第2批次考情分析

    难度     354人已做
    查看
  • 【考后总结】2024年5月25日信息系统项目管理师第1批次考情分析

    难度     318人已做
    查看
  • 2024年上半年软考高项第一、二批次真题考点汇总(完整版)

    难度     435人已做
    查看
  • 2024年上半年系统架构设计师考试综合知识真题

    难度     224人已做
    查看

相关文章

发现更多好内容

猜你喜欢

AI推送时光机
位置:首页-资讯-后端开发
咦!没有更多了?去看看其它编程学习网 内容吧
首页课程
资料下载
问答资讯