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

摘要:
因此,本期将为您带来一篇关于Swagger最新版本的文章。本文将向您展示Swagger最新版本的变化?如何将旧版本的Swagger升级到新版本?Swagger是一个用于生成、描述和调用RESTful接口的Web服务。Swagger 2.9.2的使用分为以下四个步骤:添加依赖项、启用Swagger功能、配置Swagger文档摘要信息和调用接口访问。让我们分别来看一下。

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 页面,我们可以直接进行接口调用,降低了项目开发阶段的调试成本

image.png

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”关键字,得到结果的前两条依赖信息,就是我们想要的结果,如下图所示:
image.png
将这两个依赖添加带项目中:

<!-- 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 {
    @Bean
    public 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页面,如下图所示:
image.png

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 {
    @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

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

4.访问Swagger

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

新版本 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中文社群」查看本文(Swagger 3)视频版内容。

免责声明:文章转载自《最新版Swagger 3升级指南和新功能体验!》仅用于学习参考。如对内容有疑问,请及时联系本站处理。

上篇CyclicBarrier:人齐了,老司机就可以发车了!阿里巴巴Druid,轻松实现MySQL数据库连接加密!下篇

宿迁高防,2C2G15M,22元/月;香港BGP,2C5G5M,25元/月 雨云优惠码:MjYwNzM=

相关文章

【Java】Swagger2 结合spring boot 请求接口自动生成文档

官方地址:https://swagger.io/功能主要有 1、提供后台访问地址,可对接口测试 2、生成各种离线文档 3、结合mock导入 swagger-ui 1、 maven依赖 <dependency> <groupId>io.springfox</groupId>...

Swagger+AutoRest 生成web api客户端(.Net)

简介 对于.net来说,用web api来构建服务是一个不错的选择,都是http请求,调用简单,但是如果真的要在程序中调用,则还有些工作要做,比如我们需要手写httpClient调用,并映射Model, 如果服务少还可以,多了就繁琐了。 Swagger 关于Swagger的信息,其他博客已经有介绍,这里就不多说。 大家可以参考http:...

接口文档谁来维护的问题

前言 同事说起接口文档伪造的数据你们都保存到哪了?有说提交到测试用例的, 有说不想写测试用例的, 还有说swagger的...好像想到了一个比swagger强大的东西 正文 以下为转载正文: https://blog.csdn.net/jcmj123456/article/details/110366809 JApiDocs是一个无需额外注解、开箱即用的Sp...

使用Swagger2构建SpringMVC项目中的Restful API文档

使用Swagger自动生成API文档,不仅增加了项目的可维护性,还提高了API的透明度更利于快速测试等工作,便于更快地发现和解决问题。 本篇文章只记录整合过程,关于Security Configuration等其他特性这里就不展开讲了,感兴趣的可以通过以下链接了解更多。 参考文档: https://howtodoinjava.com/swagger...

Swagger介绍-一套流行的API框架

简介 号称:世界最流行的API框架 官网:http://swagger.io/ 解决什么问题:在前后台分离的开发模式中,减小接口定义沟通成本,方便开发过程中测试,自动生成接口文档。 实例代码位置:https://github.com/pumadong/cl-roadshow/tree/master/roadshow-swagger swagger使...

swagger 的使用

最近在用 .Net Core 做项目 了解到swagger 是一个不错的工具 简单介绍一下 在使用asp.net core 进行api开发完成后,书写api说明文档对于程序员来说想必是件很痛苦的事情吧,但文档又必须写,而且文档的格式如果没有具体要求的话,最终完成的文档则完全取决于开发者的心情。或者详细点,或者简单点。那么有没有一种快速有效的方法来构...

最新文章