来源|Java中文社区（ID：javacn666）转载请联系授权（微信ID：GG_Stone）Swagger3.0已经发布有一段时间了，2020年7月发布，但目前市面上的主流版本还是Swagger2.X版本和少量的1.X版本，但是一个合格的程序员怎么能不折腾新技术呢？那么本期就为大家带来最新版的Swagger。本文将向您展示最新版本的Swagger有哪些变化？如何将旧版本的Swagger升级到新版本？什么是招摇？Swagger是一种用于生成、描述和调用RESTful接口的Web服务。通俗地说，Swagger就是一个服务，将项目中所有（想暴露的）接口展示在页面上，可以进行接口调用和测试。PS：Swagger遵循OpenAPI规范，这是Linux基金会的一个项目，试图通过定义一种用于描述API格式或API定义的语言来规范RESTful服务开发过程。Swagger官网地址：https://swagger.io/Swagger有什么用？从上面的Swagger定义，我们不难看出Swagger有以下三个重要的功能：将项目中的所有接口显示在页面上，这样后端程序员就不用为前端用户写专门的接口文档了；接口更新时，只需修改代码中的Swagger描述即可实时生成新的接口文档，避免接口文档老旧不能使用的问题；通过在Swagger页面上，我们可以直接调用接口，减少了项目开发阶段的调试成本。旧版Swagger使用的是旧版Swagger，即市面上主流的V2版本是Swagger2.9.2。在说新版本之前，我们先来回顾一下Swagger2.9.2是如何使用的。Swagger2.9.2的使用分为以下4个步骤：添加依赖启用Swagger功能配置Swagger文档摘要信息调用接口访问下面分别来看。1、添加依赖首先我们去mvnrepository查询Swagger的依赖，搜索“springfox”关键字，得到结果的前两个依赖，也就是我们想要的结果，如下图：在项目中添加这两个依赖项：io.springfoxspringfox-swagger2<版本>2.9.2groupId>io.springfoxspringfox-swagger-ui2.9.2为什么是“springfox”？Q：我们使用的是Swagger，为什么要搜索“springfox”？答：Swagger可以看作是一种遵循OpenAPI规范的技术，而springfox就是这种技术的具体实现。就像Spring中的AOP和DI一样，前者是思想，后者是实现。2、开启Swagger在SpringBoot的启动类或配置类中添加@EnableSwagger2注解，开启Swagger。部分核心代码如下：@EnableSwagger2@SpringBootApplicationpublicclassApplication{...3.配置摘要信息importorg.springframework.context.annotation.Bean；importorg.springframework.context.annotation.Configuration;importspringfox.documentation.builders.RequestHandlerSelectors;importspringfox.documentation.spi.DocumentationType;importspringfox.documentation.spring.web.plugins.Docket;importspringfox.documentation.swagger2.annotations.EnableSwagger2;@ConfigurationpublicclassSwaggerConfiguration{@BeanpublicDocketcreateRestApi(){returnnewDocket(DocumentationType.SWAGGER_2)//1.SWAGGER_2.select().apis(RequestHandlerSelectors.basePackage("com.example.swaggerv2.controller"))//2.setscanpath.build();}}4.访问Swagger工程正常启动后，使用“http://localhost:8080/swagger-ui.html”访问Swagger页面，如下图：最新版本的Swagger使用最新版本的Swagger。配置步骤和老版本一样，只是各个具体的配置项略有不同，具体步骤如下。1.添加依赖io.springfoxspringfox-boot-starter3.0.0从上面的配置可以看出新版Swagger只有一个依赖，而旧版有两个依赖，相对说话简洁多了。2、开启Swagger在SpringBoot的启动类或配置类中添加@EnableOpenApi注解，开启Swagger。部分核心代码如下：@EnableOpenApi@SpringBootApplicationpublicclassApplication{...3.配置概要信息importorg.springframework.context.annotation.Bean；importorg.springframework.context.annotation.Configuration；importspringfox.documentation.builders.RequestHandlerSelectors；importspringfox.documentation.oas.annotations.EnableOpenApi；importspringfox.documentation.spi.DocumentationType；{@BeanpublicDocketcreateRestApi(){returnnewDocket(DocumentationType.OAS_30)//v2不同.select().apis(RequestHandlerSelectors.basePackage("com.example.swaggerv3.controller"))//设置扫描路径.build();}}从上面的代码可以看出，在Docket的配置中，新旧版本只是文档类型的设置不同。新版本配置为OAS_30，旧版本配置为SWAGGER_2。PS：OAS是OpenAPISpecification的缩写，翻译成中文就是OpenAPI规范。4、新版Swagger的访问地址与旧版不同。新版本的访问地址为“localhost:8080/swagger-ui/”，如下图：新版本VS旧版本新版本与旧版本的区别主要体现在以下四个方面：添加依赖项不同：新版本只需要添加一项，而旧版本需要添加两项；启动Swagger的注解不同：新版本使用@EnableOpenApi，而旧版本使用@EnableOpenApi，是@EnableSwagger2；Docket（文档摘要信息）的文件类型配置不同：新版本配置为OAS_3，旧版本配置为SWAGGER_2；SwaggerUI访问地址不同：新版本访问地址为“http://localhost:8080/swagger-ui/”，而旧版本访问地址为“http://localhost:8080/swagger-ui”.html”。总结一下，新版Swagger有两个令人印象深刻的优势：一是配置变得更简单，比如依赖配置减少了50%，二是新版Swagger页面设计风格发生了很大变化，新版页面让人感觉更加现代科技，总的来说，好看了很多。值得一提的是，Swagger的整个升级过程非常顺利。从旧版本升级到新版本，只需要简单的配置。用于描述接口的注解仍然沿用旧版本的用法，这样可以在大部分主要代码的情况下，顺利到达最新版本。
