SpringBoot實戰：SpringBoot之Swagger集成

Swagger是什麼？Swagger 是一個規範且完整的框架，用於生成、描述、調用和可視化 RESTful 風格的 Web 服務。Swagger 的目標是對 REST API 定義一個標準且和語言無關的接口，可讓人和計算機擁有無須訪問源碼、文檔或網絡流量監測就能夠發現和理解服務的能力。當經過 Swagger 進行正肯定義，用戶能夠理解遠程服務並使用最少實現邏輯與遠程服務進行交互。與爲底層編程所實現的接口相似，Swagger 消除了調用服務時可能會有的猜想。

Swagger 的優點有哪些

1. 支持 API 自動生成同步的在線文檔：使用 Swagger 後能夠直接經過代碼生成文檔，再也不須要本身手動編寫接口文檔了，對程序員來講很是方便，能夠節約寫文檔的時間去學習新技術。
2. 提供 Web 頁面在線測試 API：光有文檔還不夠，Swagger 生成的文檔還支持在線測試。參數和格式都定好了，直接在界面上輸入參數對應的值便可在線測試接口。

SpringBoot集成Swagger很方便，接下來將演示如何集成

首先pom.xml引入相關依賴

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

建立Swagger配置類

import org.springframework.context.annotation.Bean;
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.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
* @author wusy
* Company: xxxxxx科技有限公司
* Createtime : 2018年9月3日 下午1:47:48
* Description : 
*/
@EnableSwagger2
@Configuration
public class SwaggerConfigurer {

	@Bean
	public Docket createRestApi() {
		return new Docket(DocumentationType.SWAGGER_2)
				.apiInfo(apiInfo())
				.select().apis(RequestHandlerSelectors.basePackage("com.wusy.demo"))
				.paths(PathSelectors.any())
				.build();
	}

	private ApiInfo apiInfo() {
		ApiInfoBuilder builder = new ApiInfoBuilder();
		builder.title("spring-boot-wusy-demo");
		builder.description("spring-boot-wusy-demo rest full api文檔");
		builder.version("1.0");
		return builder.build();
	}
}

這裏記住@EnableSwagger2這個註解是必不可少的，最後編寫Rest Full接口

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RestController;

/**
 * @author wusy
 * Company: xxxxxx科技有限公司
 * Createtime : 2020/3/4 23:22
 * Description :
 */
@Api(tags = {"Swagger集成演示相關接口"})
@RestController
@RequestMapping("/api/swagger")
public class SwaggerDemoController {

    @ApiOperation("Swagger集成示例")
    @RequestMapping(value = "/demo", method = RequestMethod.GET)
    public String demo(@ApiParam(required = true , name = "param") String param) {
        return param;
    }
}

到這裏集成Swagger完成，接下來咱們啓動項目而後在瀏覽器中輸入http://127.0.0.1:8787/swagger-ui.html，觀察結果

提示出錯了，這裏提示base url被攔截了，經過觀察網絡請求發現

經過分析原來是以前在配置自定義方法接口的時候把swapper接口也給攔截了，因此要原來的改造下

/**
 * @author wusy
 * Company: xxxxxx科技有限公司
 * Createtime : 2020/2/28 22:04
 * Description : rest full 全局統一返回封裝
 */
@RestControllerAdvice
public class GlobalControllerAdvice implements ResponseBodyAdvice<Object> {

    private Logger logger = LoggerFactory.getLogger(GlobalControllerAdvice.class);

    /**
     * 須要忽略的地址
     */
    private static String[] ignores = new String[]{
            //過濾swagger相關的請求的接口，否則swagger會提示base-url被攔截
            "/swagger-resources",
            "/v2/api-docs"
    };

    /**
     * 判斷哪些須要攔截
     * @param returnType
     * @param converterType
     * @return
     */
    @Override
    public boolean supports(MethodParameter returnType, Class<? extends HttpMessageConverter<?>> converterType) {
        return true;
    }

    /**
     * 判斷url是否須要攔截
     * @param uri
     * @return
     */
    private boolean ignoring(String uri) {
        for (String string : ignores) {
            if (uri.contains(string)) {
                return true;
            }
        }
        return false;
    }

    @Override
    public Object beforeBodyWrite(Object body, MethodParameter returnType, MediaType selectedContentType, Class<? extends HttpMessageConverter<?>> selectedConverterType, ServerHttpRequest request, ServerHttpResponse response) {
        //判斷url是否須要攔截
        if (this.ignoring(request.getURI().toString())) {
            return body;
        }
        //若是返回的數據是ResultObjectModel、Byte類型則不進行封裝
        if( body instanceof ResultObjectModel || body instanceof Byte || body instanceof String) {
            return body;
        }
        return this.getWrapperResponse(request , body);
    }
  
    /**
     * 返回正常的信息
     * @param request
     * @param data
     * @return
     */
    private ResultObjectModel<Object> getWrapperResponse(ServerHttpRequest request, Object data) {
        return new ResultObjectModel<>(true, "請求成功" , data);
    }
}

重啓應用，這裏要重啓瀏覽器後訪問http://127.0.0.1:8787/swagger-ui.html，觀察結果

至此Swagger集成成功。

集成Swagger的時候要注意如下幾點：

一、@EnableSwagger2註解必定要添加

二、自定義接口ResponseBodyAdvice中是否對swagger的相關接口作了處理，本次演示中就是由於這個問題致使出現問題

三、過濾器是否對swagger的相關接口作了處理

四、集成security時若是swagger不須要登錄就能訪問的話應該要對swagger的相關進行不攔截

@Override
public void configure(WebSecurity web) {
    //swagger相關的頁面和接口不攔截
	web.ignoring().antMatchers("/swagger-ui.html")
			      .antMatchers("/webjars/springfox-swagger-ui/**")
				  .antMatchers("/swagger-resources/**" )
				  .antMatchers("/v2/api-docs/**");
}