JavaWeb：Swagger基础使用日记，以及错误error处理

摘要： 本篇文章主要介绍我在SpringBoot项目中使用Swagger的基础步骤、体会和异常error解决。

一、Swagger概述

概念：Swagger是一个SpringBoot依赖，是一个接口文档生成工具。
作用：能够把Controller暴露的API展示为一个HTML文档，这个文档会根据Controller中的代码和注释实时更新。
现实中解决的问题是：增加前后端分离的协同性。让接口文档 规范化、实时更新、由程序自动生成而不必多花费时间和经历去写。

二、Swagger基本使用

配置信息如下：
操作系统：Windows10
JDK版本：1.8
集成开发环境：IDEA
Maven版本：3.8.1
SpringBoot版本：2.5.8(最好使用这个版本，不然需要额外解决很多琐事，不利于使用)
springfox-swagger-ui和springfox-swagger2版本：3.0.0
1、添加Swagger依赖

    io.springfox
    springfox-boot-starter
    3.0.0

Swagger3.0版本不需要配置swagger2和swagger-ui了，直接使用springfox-boot-starter就可以搞定。

2、编写Swagger配置
以下配置先直接复制过去即可，先完成第一步。之后向详细了解可以查阅官方文档：
Swagger官方文档

@Configuration
@EnableSwagger2
public class Swagger3Config {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.OAS_30)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                .paths(PathSelectors.any())
                .build();
    }
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Swagger文档")
                .description("这是一个测试文档")
                .version("1.0.0")
                .build();
    }
}

3、编写一个示例接口，并添加Api注解

@Api(tags = "这是一个测试Controller")
@RestController
@RequestMapping("/tc")
public class TestController {
    @ApiOperation("测试post接口")
    @PostMapping("/t-post")
    public String testPost(){
        return "测试Post成功";
    }
    @ApiOperation("测试get接口")
    @GetMapping("/t-get")
    public String testGet(){
        return "测试Get成功";
    }
    @ApiOperation("测试getParam接口")
    @GetMapping("/t-getParam")
    public String testGet(@ApiParam("传入的name参数") @RequestParam(value = "name") String name){
        return "测试GetParam成功:"+name;
    }
}

@Api()作用于模块
@ApiOperation()作用于方法
@ApiParam()作用于变量
4、配置.properties或者.yml文件
打开Resource下的application.properties文件，写入如下配置或者自定义

server.port=8355
server.servlet.context-path=/m5

server.port代表指定该项目的接口
server.servlet.context-path代表指定该项目在该接口下的访问路径
5、访问swagger-ui查看文档
访问如下网址：
你的项目swagger-ui地址
或者浏览器输入：
http://localhost:8355/m5/swagger-ui/index.html#/

这里的8355是端口号，在第四步使用server.port指定，如果未指定，默认是8080。
/m5是项目应用路径，在第四步使用server.servlet.context-path指定，如果未指定可以省略。

即可访问swagger3页面。如图：

三、错误解决

异常1： ‘documentationPluginsBootstrapper’; nested exception is java.lang.NullPointer…
这个异常网上一直再将问题归结于Swagger和SpringBoot版本不对应，可以在pom.xml中修改SpringBoot版本为2.5.8，退出IDEA并且重新进入即可（同步maven或者Rebuild可能会卡住）
异常2 访问swagger-ui页面显示404空白页面，原因是使用了@EnableWebMVC注解，需要将该注解移除。
异常3 如果没有使用@EnableWebMVC注解，还是访问了一个404界面，那么说明浏览器输入的URL错误，在以下这篇文章里有讲清楚
URL错误