Springboot2 集成Swagger2，解决配置完成后不显示的坑

为新项目做准备重新搭建环境，决定使用Springboot2+mybatis环境，使用shiro做权限管理，并搭配pagehelper，generator等。在配置Swagger2的时候出现访问时界面空白的坑，刚开始以为是配置的插件过多导致的不兼容，重新配置了其他环境，但问题依然存在，后来查找资料解决了问题。现在此作记录。目前使用Springboot 版本为  2.0.3.RELEASE。

一、springboot2导包（maven）：

在pom.xml中

<!--Swagger2-->
<dependency>
   <groupId>io.springfox</groupId>
   <artifactId>springfox-swagger2</artifactId>
   <version>${springfox-swagger2.version}</version>
</dependency>
<dependency>
   <groupId>io.springfox</groupId>
   <artifactId>springfox-swagger-ui</artifactId>
   <version>${springfox-swagger2.version}</version>
</dependency>

<springfox-swagger2.version>2.8.0</springfox-swagger2.version>

二、Swagger2配置

    新建Swagger2配置文件Swagger2Config.java

    配置文件Swagger2Config.java中：支持多个api文档

//注解开启 swagger2 功能
@EnableSwagger2
//注解标示,这是一个配置类,@Configuation注解包含了@Component注解
//可以不用在使用@Component注解标记这是个bean了
@Configuration
@EnableWebMvc
public class Swagger2Config implements WebMvcConfigurer {
    @Value("${base.location}")//项目初始目录  一般就是自己springboot启动类的包名

    private String baseLocation;

    /**
     * 将Swagger2 的swagger-ui.html加入资源路径下,否则Swagger2静态页面不能访问。要想使资源能够访问，可以有两种方法
     * 一：需要配置类继承WebMvcConfigurationSupport 类，实现addResourceHandlers方法。
     *      但是实现了WebMvcConfigurationSupport以后，Spring Boot的 WebMvc自动配置就会失效，具体表现比如访问不到
     *      静态资源（js，css等）了，这是因为WebMvc的自动配置都在WebMvcAutoConfiguration类中，但是类中有这个注解
     *      @ConditionalOnMissingBean({WebMvcConfigurationSupport.class})，意思是一旦在容器中检测到
     *      WebMvcConfigurationSupport这个类，WebMvcAutoConfiguration类中的配置都不生效。
     *      所以一旦我们自己写的配置类继承了WebMvcConfigurationSupport，相当于容器中已经有了WebMvcConfigurationSupport，
     *      所有默认配置都不会生效，都得自己在配置文件中配置。
     * 二：继承WebMvcConfigurer接口，这里采用此方法 网上有人说使用该方法会导致date编译等问题，可能在配置文件中得到解决，
     *      本人没有碰到，不多做解释
     * @param registry
     */
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("swagger-ui.html")
                .addResourceLocations("classpath:/META-INF/resources/");

        registry.addResourceHandler("/webjars/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/");
    }

    /**
     * 通过 createRestApi函数来构建一个DocketBean
     * 函数名,可以随意命名,喜欢什么命名就什么命名
     * 接口文档默认访问路径http://localhost:8080/swagger-ui.html，
     *          配置文件中有配置此处为http://localhost:8080/springboot2/swagger-ui.html
     * 注解说明参考博客：https://blog.csdn.net/qq_28009065/article/details/79104103，
     */

    @Bean
    public Docket commonDocket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("通用API接口文档")
                .apiInfo(apiInfo("测试环境通用接口"))
                .pathMapping("/")
                .select()
                .apis(RequestHandlerSelectors.basePackage(baseLocation+".web.controller"))//指向自己的controller即可
                .paths(PathSelectors.any())
                .build();
    }
    //
//    @Bean
//    public Docket normalUserDocket() {
//        return new Docket(DocumentationType.SWAGGER_2)
//                .groupName("普通用户API文档")
//                .apiInfo(apiInfo("提供普通用户接口"))
//                .protocols(Sets.newHashSet("https","http"))
//                .produces(Sets.newHashSet("html/text"))
//                .pathMapping("/")
//                .select()
//                .apis(RequestHandlerSelectors.basePackage(baseLocation+".controller.candidate"))//设置生成的Docket对应的Controller为candidate下的所有Controller
//                .paths(PathSelectors.any())
//                .build();
//    }
//
//    @Bean
//    public Docket companyUserDocket() {
//        return new Docket(DocumentationType.SWAGGER_2)
//                .groupName("企业用户API接口文档")
//                .apiInfo(apiInfo("提供企业用户接口"))
//                .pathMapping("/")
//                .select()
//                .apis(RequestHandlerSelectors.basePackage(baseLocation+".controller.company"))
//                .paths(PathSelectors.any())
//                .build();
//    }
//设置文档信息
    private ApiInfo apiInfo(String desc) {
        return new ApiInfoBuilder()
                //页面标题
                .title(desc)
                //设置作者联系方式,可有可无
                .contact(new Contact("chaoge", "https://my.csdn.net/xiaochaogge", "z28126308@163.com"))
                //版本号
                .version("1.0")
                //描述
                .description("API 描述")
                .build();

    }
}

/*
    Docket类的方法：
    Docket groupName(String var):设置栏目名

    Docket apiInfo(ApiInfo apiInfo):设置文档信息

    Docket pathMapping(String path):设置api根路径

    Docket protocols(Set<String> protocols):设置协议，Sets为com.goolge.common下的类，Sets.newHashSet("https","http")相当于new HashSet(){{add("https");add("http");}};

    ApiSelectorBuilder select():初始化并返回一个API选择构造器



    ApiSelectorBuilder类的方法：

    ApiSelectorBuilder apis(Predicate<RequestHandler> selector):添加选择条件并返回添加后的ApiSelectorBuilder对象

    ApiSelectorBuilder paths(Predicate<String> selector):设置路径筛选，该方法中含一句pathSelector = and(pathSelector, selector);表明条件为相与



    RequestHandlerSelectors类的方法：

    Predicate<RequestHandler> any()：返回包含所有满足条件的请求处理器的断言，该断言总为true

    Predicate<RequestHandler> none()：返回不满足条件的请求处理器的断言,该断言总为false

    Predicate<RequestHandler> basePackage(final String basePackage)：返回一个断言(Predicate)，该断言包含所有匹配basePackage下所有类的请求路径的请求处理器



    PathSelectors类的方法：

    Predicate<String> any():满足条件的路径，该断言总为true

    Predicate<String> none():不满足条件的路径,该断言总为false

    Predicate<String> regex(final String pathRegex):符合正则的路径



设置swagger-ui.html默认路径，servlet的配置文件添加:

    <mvc:annotation-driven></mvc:annotation-driven>
    <mvc:resources mapping="/webjars/**" location="classpath:/META-INF/resources/webjars"/>

    swagger-ui.html位于springfox-swagger-ui jar包中的META-INF/resources/目录下，项目编译后swagger-ui.html将添加到classpath的/META-INF/resources/下，所以添加mapping="/webjars/**" 可通过localhost:端口号/项目名/swagger-ui.html打开SwaggerUI

常用注解:

    Swagger所有注解并非必须，若不加就只显示类目/方法名/参数名没有注释而已，但若注解中含@ApiParam不对应@RequestParam将无效果

    @Api:注解controller，value为@RequestMapping路径

    @ApiOperation:注解方法，value为简要描述,notes为全面描述,hidden=true Swagger将不显示该方法，默认为false

    @ApiParam:注解参数,hidden=true Swagger参数列表将不显示该参数,name对应参数名，value为注释，defaultValue设置默认值,allowableValues设置范围值,required设置参数是否必须，默认为false

    @ApiModel:注解Model

    @ApiModelProperty:注解Model下的属性，当前端传过来的是一个对象时swagger中该对象的属性注解就是ApiModelProperty中的value

    @ApiIgnore:注解类、参数、方法，注解后将不在Swagger UI中显示


*/

在application.properties中（网上有人可能出现的date格式错误等问题，笔者目前还没有出现此类问题，但是也贴出有关的配置供参考）

spring.jackson.serialization.indent_output=true
spring.jackson.serialization.write-dates-as-timestamps=true
spring.http.converters.preferred-json-mapper=jackson
#设置时区
spring.jackson.time-zone=GMT+8
spring.jackson.date-format=yyyy-MM-dd HH:mm:ss
spring.jackson.joda-date-time-format=yyyy-MM-dd HH:mm:ss

新建WebMVCCongig.java类实现WebMvcConfigurer接口（没有这步操作Swagger2已经可以使用）设置跨域请求

@Configuration
public class WebMVCConfig implements WebMvcConfigurer {

    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry){
        registry.addResourceHandler("/static/**")
                .addResourceLocations("classpath:/static/");
    }

    @Override
    public void addCorsMappings(CorsRegistry registry) {
        registry.addMapping("/**")//设置允许跨域的路径
                .allowedOrigins("*")//设置允许跨域请求的域名
                .allowCredentials(true)//是否允许证书 不再默认开启
                .allowedMethods("GET", "POST", "PUT", "DELETE")//设置允许的方法
                .maxAge(3600);//跨域允许时间
    }
}

三、在controller类中

@CrossOrigin
@RestController
@RequestMapping("/test")
@Api(tags="测试类",value="测试类")
public class TestController {
    @ApiOperation(value="【PC端】提交订单", notes="提交一组识别的标签id，返回生成的订单详情")
    @RequestMapping(value = "/test/{id}", method = RequestMethod.POST, produces  = "application/json;charset=UTF-8")
    public Integer test(@PathVariable Integer id){
        System.out.println(id);
        return id;
    }
}

四、效果图

以上仅供参考，如果各位遇到其他问题也欢迎互相探讨