一、Swagger2簡單介紹

　　Swagger2，它可以輕鬆的整合到Spring Boot中，並與Spring MVC程式配合組織出強大RESTful API文件。它既可以減少我們建立文件的工作量，同時說明內容又整合入實現程式碼中，讓維護文件和修改程式碼整合為一體，可以讓我們在修改程式碼邏輯的同時方便的修改文件說明。另外Swagger2也提供了強大的頁面測試功能來除錯每個RESTful API。

二、Spring Boot整合Swagger2步驟

1）引入Swagger2的Maven座標

 <!--swagger-->
            <dependency>
                <groupId>io.springfox</groupId>
                <artifactId>springfox-swagger2</artifactId>
                <version>2.8.0</version>
            </dependency>
            <dependency>
                <groupId>io.springfox</groupId>
                <artifactId>springfox-swagger-ui</artifactId>
                <version>2.8.0</version>
            </dependency>

2) 加入Swagger2的Java配置類

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

/**
 * @author zhangboqing
 * @date 2018/8/6
 *
 * swagger2配置
 *
 * 訪問地址：
 * 
 
http://localhost:8080/swagger-ui.html
 */
@Configuration
@EnableSwagger2
public class Swagger2Config {


    @Bean
    public Docket docket() {
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select()
                //當前包路徑
                .apis(RequestHandlerSelectors.basePackage("com.zbq.springbootbase.controller"))
                .paths(PathSelectors.any()).build();

    }

    //構建api文件的詳細資訊函式
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                //頁面標題
                .title("springboot-base-frame,使用Swagger2構建RESTful API")
                //建立人
                .contact(new Contact("張波清", "[email protected]", ""))
                //版本號
                .version("1.0")
                //描述
                .description("API 描述")
                .build();


    }

}

3）在Controller方法上加上  @ApiOperation(value="測試", notes="這是一個簡單測試方法"),再不用加任何註解。

/**
 * @author zhangboqing
 * @date 2018/9/24
 */
@RestController
public class TestController {

    @ApiOperation(value="測試", notes="這是一個簡單測試方法")
    @PostMapping(value = "/test")
    public String test(@RequestHeader String myHeader,String myName) {
        System.out.println("----------->header測試");

        System.out.println(myHeader);
        System.out.println(myName);
        return myHeader;
    }

}

4）若使用了Spring Boot 的攔截器，需要過濾Swagger，確保它不被攔截

　　加入如下標記為藍色的過濾配置，就可以了

/**
 * @author zhangboqing
 * @date 2018/8/7
 *
 * 註冊攔截器
 */
@Configuration
public class ApiSecurityConfig2 implements WebMvcConfigurer {



    @Bean
    LoggingInterceptor loggingInterceptor() {
        return new LoggingInterceptor();
    }

    /**
     * 攔截請求
     *
     * @param registry
     */
    @Override
    public void addInterceptors(InterceptorRegistry registry) {
        //註冊日誌攔截器
        registry.addInterceptor(loggingInterceptor())
                //新增需要攔截的路徑
                .addPathPatterns("/**")
                .excludePathPatterns("/swagger-resources/**", "/webjars/**", "/v2/**", "/swagger-ui.html/**");

    }

    @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/");
    }

    /**
     * 跨域配置
     *
     * @param registry
     */
    @Override
    public void addCorsMappings(CorsRegistry registry) {
//        registry.addMapping("/**")
//                // TODO 這裡跨域最好配置域名
//                .allowedOrigins("*")
//                .maxAge(3600)
//                .allowCredentials(true)
//                .allowedMethods("GET", "POST", "OPTIONS");
    }
}

三、效果展示 

啟動你的專案，訪問Swagger2文件地址：http://localhost:8080/swagger-ui.html