目录
前言
之前在工作团队合作时发现项目里的swagger依赖配置一大堆，一直没去在意，抱着能用就行的心态使用；
直到最近自己做项目在springcloud的gateway中加入swagger2时遇到了无法启动的问题，原来是swagger版本太旧了，无法适应webflux响应式编程，在更新依赖时也是一直踩坑；
因此在此总结swagger的各个依赖版本升级及其配置
依赖版本分析
swagger2
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>${swagger.version}</version>
</dependency>
此依赖为swagger的主要依赖，用于将swagger整合到系统
纵观所有依赖版本：
2.0.1~2.9.2
-
从
2.0.1到2.9.2都是swagger2阻塞式编程，servlet3.1之前的版本，都差不多，最常用的就是2.9.2在配置swagger时，使用的注解即为
@EnableSwagger2
2.10.0~2.10.5
- 从2020年1月开始的
2.10.0开始，由于响应式编程逐渐出现，WebFlux中Netty的高性能出现，于是swagger也开始更新- 从
2.10.0至2.10.5，swagger2的配置时，使用的注解开始分为@EnableSwagger2WebMvc和@EnableSwagger2WebFlux，用于区分阻塞式编程框架和响应式编程框架，并直接去除了@EnableSwagger2注解 - 但是此时出现一个问题：不利于维护，注解需要全部改掉，因此2.10版本可以理解为一个测试版本
- 从
3.0.0
基于之前2.10版本，swagger3正式推出，非阻断式升级兼容阻塞式编程和响应式编程，因此在swagger2的依赖中，仍然有3.0.0版本
-
配置注解
@EnableSwagger2WebMvc和@EnableSwagger2WebFlux两个注解deprecated，兼容的注解为@EnableOpenAPI或@EnableSwagger2；开发者也考虑到了非阻断式升级，所以此处使用这两个注解都可以 -
UI访问页地址
-
swagger2的访问uri为：
/swagger-ui.html -
swagger3的访问uri为：
/swagger-ui/index.html
-
-
整合依赖
-
swagger2
在swagger2版本中，需要使用swagger2，并可以从浏览器中ui渲染，必须导入两个依赖
springfox-swagger2与springfox-swagger-ui<dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>${swagger2.version}</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>${swagger2.version}</version> </dependency> -
swagger3
swagger3版本中，官方推出了整合依赖
springfox-boot-starter代替了之前可能的复杂的依赖配置，一个依赖，全部导入<dependency> <groupId>io.springfox</groupId> <artifactId>springfox-boot-starter</artifactId> <version>3.0.0</version> </dependency>对于其他分开依赖的导入，还没找到合适的多个依赖导入成功的方法，这个单个组合依赖是最好的方法
-
其他依赖说明
swagger-ui
作为swagger的ui渲染依赖，如果需要在浏览器中查看ui，则这个依赖是必须的
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>${swagger2.version}</version>
</dependency>
swagger-models
swagger-annotations
-
swagger-models与annotations也有自己的脱离swagger2的依赖版本管理，但他们是swagger2依赖的包含依赖，即在swagger2中已经有对应版本的依赖了，不建议再进行额外的版本控制 -
二者在
1.5.0~1.6.5基本差不多，用的最多的是1.5.21在
2.0.0-rc0开始，如果使用这个版本，则原本的实体类的那套注解开始失效，具体原因未知再后面，依赖的
groupId更改，就开始转向io.swagger.core.v3了由
<dependency> <groupId>io.swagger</groupId> <artifactId>swagger-models</artifactId> </dependency>转为
<dependency> <groupId>io.swagger.core.v3</groupId> <artifactId>swagger-models</artifactId> </dependency>但是和
2.0.0-rc开始一样的问题，不兼容swgger2 -
swagger2中额外的版本控制示例：<dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <exclusions> <exclusion> <groupId>io.swagger</groupId> <artifactId>swagger-annotations</artifactId> </exclusion> <exclusion> <groupId>io.swagger</groupId> <artifactId>swagger-models</artifactId> </exclusion> </exclusions> <version>2.9.2</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.9.2</version> </dependency> <dependency> <groupId>io.swagger</groupId> <artifactId>swagger-annotations</artifactId> <version>1.5.21</version> </dependency> <dependency> <groupId>io.swagger</groupId> <artifactId>swagger-models</artifactId> <version>1.5.21</version> </dependency>极其不建议将此作为父工程依赖管理，因为会影响其他模块子工程的依赖导入，可能会造成启动异常
NoClassDefFoundError: springfox/documentation/spring/web/PropertySourcedRequestMappingHandlerMappingNoClassDefFoundError: springfox/documentation/spring/web/PropertySourcedRequestMappingHandlerMapping
springfox-spring-webflux
作为webflux的依赖额外开发，单独出现，不常用，也不建议分开导入
项目配置
swagger2配置
导入依赖
<!--Swagger依赖-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
配置类
package com.slipperysoap.system.config;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
/**
* @author slipperySoap
* @version 1.0
* ClassName: SwaggerConfig
* Description: Swagger配置类
* Date: 2022/2/16 4:08
*/
@Configuration
// 开启swagger2
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket docket() {
ApiInfo apiInfo =
new ApiInfoBuilder()
.title("5101Club日常管理系统API——System")
.description("管理系统采用SpringBoot开发，API文档集成Swagger")
.version("1.0")
.contact(new Contact("slipperySoap", "https://github.com/stupidSoap", "slipperysoap@qq.com"))
.license("Apache 2.0")
.licenseUrl("http://www.apache.org/licenses/LICENSE-2.0")
.build();
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo)
.select()
// 配置swagger显示的controller，如果不配置则默认扫描所有后端接口
.apis(RequestHandlerSelectors.basePackage("com.slipperysoap.system.controller"))
.paths(PathSelectors.any())
.build();
}
}
运行测试
swagger2访问uri：/swagger-ui.html
比如url为：http://localhost:2000/swagger-ui.html
如果配置类中不加信息则是默认页
如果配置了作者信息和扫描包则是自定义页面
swagger3配置
导入依赖
<!--Swagger依赖-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-boot-starter</artifactId>
<version>3.0.0</version>
</dependency>
配置类
package com.slipperysoap.gateway.config;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
/**
* @author slipperySoap
* @version 1.0
* ClassName: SwaggerConfig
* Description: Swagger配置类
* Date: 2022/2/16 4:08
*/
@Configuration
// 开启swagger2
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket docket() {
ApiInfo apiInfo =
new ApiInfoBuilder()
.title("5101Club日常管理系统API——Gateway")
.description("管理系统采用SpringBoot开发，API文档集成Swagger")
.version("1.0")
.contact(new Contact("slipperySoap", "https://github.com/stupidSoap", "slipperysoap@qq.com"))
.license("Apache 2.0")
.licenseUrl("http://www.apache.org/licenses/LICENSE-2.0")
.build();
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo)
.select()
// 配置swagger显示的controller，如果不配置则默认扫描所有后端接口
.apis(RequestHandlerSelectors.basePackage("com.slipperysoap.gateway.controller"))
.paths(PathSelectors.any())
.build();
}
}
运行测试
swagger3访问uri：swagger-ui/index.html
比如url为：http://localhost:1200/swagger-ui/index.html
如果配置类中不加信息则是默认页
如果配置了作者信息和扫描包则是自定义页面
可能出现的错误
-
404错误页
-
依赖缺失错误页
-
两种错误都可能是依赖导入错误，或者父工程依赖管理中使用了
<exclusive>把部分包含依赖排除了，去掉<exclusive>即可解决
参考
- SpringFox 3.0.0（包含springfox-swagger2-3.0.0）——无法访问/swagger-ui.html解决方案——等你的夏天
- springfox-swagger-ui 3.0.0 配置，springfox-boot-starter 配置——雨季余静
- Swagger3.0.0配置——loongod
- github报错讨论"NoClassDefFoundError"
如果有问题欢迎在评论区中留言
希望对大家有帮助和提供参考价值
6171
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
