前言

Swagger是一个规范和完整的框架，用于生成、描述、调用和可视化RESTful风格的Web服务。
总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法、参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。Swagger让部署管理和使用功能强大的API从未如此简单。

引入依赖

xml

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

创建Swagger配置类

java

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.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration // 标明是配置类
@EnableSwagger2 //开启swagger功能
public class SwaggerConfig {

    @Bean
    public Docket createRestApi() {
        // DocumentationType.SWAGGER_2 固定的，代表swagger2
        return new Docket(DocumentationType.SWAGGER_2)
          // .groupName("分布式任务系统") // 如果配置多个文档的时候，那么需要配置groupName来分组标识
          .apiInfo(apiInfo()) // 用于生成API信息
          .select() // select()函数返回一个ApiSelectorBuilder实例,用来控制接口被swagger做成文档
          .apis(RequestHandlerSelectors.basePackage("com.smart.demo.controller")) // 用于指定扫描哪个包下的接口
          .paths(PathSelectors.any())// 选择所有的API,如果你想只为部分API生成文档，可以配置这里
          .build();
    }

    /**
     * 用于定义API主界面的信息，比如可以声明所有的API的总标题、描述、版本
     * @return
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
          .title("测试Demo项目API") //  可以用来自定义API的主标题
          .description("测试Demo项目SwaggerAPI管理") // 可以用来描述整体的API
          .termsOfServiceUrl("") // 用于定义服务的域名
          .version("1.0") // 可以用来定义版本。
          .build(); //
    }
}

访问测试

访问链接1：http://localhost:8080/swagger-ui.html
访问链接2：http://127.0.0.1:8080/swagger-ui/index.html

遇到的问题

问题1

Failed to start bean 'documentationPluginsBootstrapper'; nested exception is java.lang.NullPointerException

原因：Swagger停更，导致其默认配置下对于高版本的SpringBoot的不兼容

SpringBoot版本 >= 2.6.x默认匹配策略为path-pattern-matcher
SpringBoot版本 < 2.6.x默认匹配策略为ant-path-matcher

解决方案1：降低SpringBoot版本

降低SpringBoot版本，SpringBoot版本<=2.5.6

xml

<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>2.5.5</version>
    <relativePath/>
</parent>

解决方案2：修改匹配策略

在 application.yml 配置文件添加配置

yml

spring:
  mvc:
    pathmatch:
      matching-strategy: ant_path_matcher

解决方案3：修改Swagger配置类
修改Swagger配置类，在SwaggerConfig类上加注解@EnableWebMvc
java
1
2
3
4
5
6
@Configuration
@EnableSwagger2
@EnableWebMvc
public class SwaggerConfig {
......
}