Springboot2 集成Swagger2，解決配置完成後不顯示的坑

爲新項目作準備從新搭建環境，決定使用Springboot2+mybatis環境，使用shiro作權限管理，並搭配pagehelper，generator等。在配置Swagger2的時候出現訪問時界面空白的坑，剛開始覺得是配置的插件過多致使的不兼容，從新配置了其餘環境，但問題依然存在，後來查找資料解決了問題。如今此做記錄。目前使用Springboot 版本爲  2.0.3.RELEASE。

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

2、Swagger2配置

    新建Swagger2配置文件Swagger2Config.java

    配置文件Swagger2Config.java中：支持多個api文檔

//註解開啓 swagger2 功能
@EnableSwagger2
//註解標示,這是一個配置類,@Configuation註解包含了@Component註解
//能夠不用在使用@Component註解標記這是個bean了
@Configuration
@EnableWebMvc
public class Swagger2Config implements WebMvcConfigurer {
    @Value("${base.location}")//項目初始目錄
    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);//跨域容許時間
    }
}

3、在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;
    }
}

4、效果圖