前言

之前在工作团队合作时发现项目里的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/PropertySourcedRequestMappingHandlerMapping

  NoClassDefFoundError: 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"

如果有问题欢迎在评论区中留言
希望对大家有帮助和提供参考价值