?一、博客概述

1 依赖引入
2 项目配置
3 实战测试

1、依赖引入

在依赖引入环节，我们需要特别注意的是 Boot 版本和 Swagger 依赖的关系。在这里，我们使用的是 2.7.3 的 Boot 和 2.9.2 的 Swagger。如果两者版本不匹配的话，会出现一些意料之外的坑；

          <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
            <!-- 排除自带的1.5.20版本-->
            <exclusions>
                <exclusion>
                    <groupId>io.swagger</groupId>
                    <artifactId>swagger-models</artifactId>
                </exclusion>
            </exclusions>
        </dependency>
        <!-- 使用1.5.22-->
        <dependency>
            <groupId>io.swagger</groupId>
            <artifactId>swagger-models</artifactId>
            <version>1.5.22</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
        </dependency>

?这里之所以要排除 20 的原因是因为实体类字段默认值的问题，如果我们在实体类中使用了 Swagger 的注解，而且定义的字段是数值类型的话，就会报异常。像下面这样：

public class SwaggerRequestVo {
    @ApiModelProperty(value = "姓名", required = true)
    private String name;
    @ApiModelProperty(value = "年龄", required = true)
    private Integer age;
}
此时，我们的 age 并没有使用 example 属性赋默认值，然后就会报下面的错误信息：
java.lang.NumberFormatException: For input string: ""

?这是因为，如果你不给这些数值字段设置默认值（使用 example 属性），它就会利用 String 赋默认值，然后就会出现这个异常信息；

2、项目配置

2.1 Swagger 主配置类

@Configuration
@EnableOpenApi
public class SwaggerConfig {
    @Bean
    public Docket getDocket() {
        // basePackage 属性指定了哪些包内的接口会被扫描进入文档内
        return new Docket(DocumentationType.OAS_30).groupName("测试Swagger02").apiInfo(getApiInfo()).select().apis(RequestHandlerSelectors.basePackage("com.mjh.controller")).build();
    }

    private ApiInfo getApiInfo() {
        return new ApiInfoBuilder().title("Swagger的入门使用").version("2.0.0").build();
    }
}

2.2 Boot 启动类

?主启动类要把我们写的 Swagger 主配置类扫描到核心容器中，否则将无法正常使用文档

@ComponentScan(basePackages = "com.mjh")
@SpringBootApplication
public class SpringBootSwaggerApplication {

    public static void main(String[] args) {
        SpringApplication.run(SpringBootSwaggerApplication.class, args);
    }

}

?3、实战测试

3.1 接口

@RestController
@RequestMapping(value = "/sc")
// Swagger 接口注解
@Api(value = "value", tags = "SwaggerController")
// lombok 日志工具注解
@Slf4j
public class SwaggerController {

    // Swagger 方法注解
    @ApiOperation(value = "tP-value", notes = "tP-notes")
    @PostMapping(value = "/tP")
    // SwaggerRequestVo 的信息在下面会展示出来
    public SwaggerRequestVo testPost(@ApiParam(value = "swaggerRequestVo", required = true) @RequestBody SwaggerRequestVo swaggerRequestVo) {
        log.info("testPost");
        return swaggerRequestVo;
    }

    @ApiOperation(value = "tG-value", notes = "tG-notes")
    @GetMapping(value = "/tG")
    public SwaggerRequestVo testGet(@ApiParam(value = "swaggerRequestVo", required = true) SwaggerRequestVo swaggerRequestVo) {
        log.info("testGet");
        return swaggerRequestVo;
    }
}

lombok 依赖：

<!--Lombok引入-->
        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
        </dependency>

SwaggerRequestVo 信息：

// lombok 注解，自动添加 set get 方法
@Data
// Swagger 注解，标注该实体类在文档中的信息
@ApiModel(value = "swaggerRequestVo", description = "Swagger测试-参数接收实体类")
public class SwaggerRequestVo {
    // Swagger 注解，标注该字段的信息
    @ApiModelProperty(value = "姓名", required = true)
    private String name;
    @ApiModelProperty(value = "年龄", required = true)
    private Integer age;
}

接下来我们可以尝试启动项目，但是你会发现它会报一个错误，错误的核心信息是这样的：

org.springframework.context.ApplicationContextException: Failed to start bean 'documentationPluginsBootstrapper'; nested exception is java.lang.NullPointerException

这里我们直接给处理方案，在主配置文件中加上这行代码，问题就会迎刃而解。原因的话手动百度下：

spring.mvc.pathmatch.matching-strategy=ANT_PATH_MATCHER

搞到这里，项目可以正常启动。所以我们可以访问到 Swagger 的在线文档页面。路径如下：

http://ip:port/swagger-ui.html

看到有页面，有对应的接口，就是成功了。但是在实际的开发中，我们通常会做出如下的操作：

首先我们会重新导入一个依赖到项目中，目的是想看到一个更符合使用习惯的UI界面；

        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>swagger-bootstrap-ui</artifactId>
            <version>1.9.6</version>
        </dependency>

然后我们访问新的地址，就可以得到一个符合国人习惯的在线接口文档界面了：