Spring Boot（八）集成swagger

以前一直維護wiki,不是用測試用例就是用postman工具，偶然的機會相遇了swagger，感受非常試用。因此決定將其配置流程乃至中間遇到的坑記錄下來。

1、何爲swagger？

Swagger 是一個規範和完整的框架,用於生成、描述、調用和可視化 RESTful 風格的 Web 服務。整體目標是使客戶端和文件系統做爲服務器以一樣的速度來更新。文件的方法,參數和模型緊密集成到服務器端的代碼,容許API來始終保持同步。Swagger 讓部署管理和使用功能強大的API從未如此簡單。

2、配置流程

maven依賴

<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>
            <dependency>
                <groupId>com.fasterxml.jackson.core</groupId>
                <artifactId>jackson-databind</artifactId>
                <version>2.9.6</version>
            </dependency>

swagger 配置類

@Configuration
@EnableSwagger2
public class SwaggerConfig {

	@Bean
	public Docket createRestApi() {
		return new Docket(DocumentationType.SWAGGER_2)
				.select()
				.apis(RequestHandlerSelectors.basePackage("com.openplatform.api.controller"))
				.paths(PathSelectors.any())
				.build()
				.globalOperationParameters(pars)
				.apiInfo(apiInfo());
	}

	private ApiInfo apiInfo() {
		return new ApiInfoBuilder()
				.title("街雲相關接口測試")
				.description("以下連接是直接跳轉到wiki的，方便快捷")
				.contact(new Contact("wiki address", "http://192.168.31.215:9999/dokuwiki/doku.php?id=start", ""))
				.license("")
				.licenseUrl("")
				.version("1.0.0")
				.build();
	}
}

3、遇到的坑

一、由於swagger是頁面化的，因此最基本的則是集成其本身的html頁面以及其樣式包
頁面錯誤展現：{「code」:404,「data」:{},「msg」:「Not Found」,「status」:false}
代碼錯誤：
未集成html的錯誤

2018-12-04 17:23:06.444|WARN ||o.s.w.s.PageNotFound|No mapping found for HTTP request with URI [/swagger-ui.html] in DispatcherServlet with name 'dispatcherServlet'
2018-12-04 17:23:06.500|ERROR||c.o.a.w.ErrorInfoBuilder|api error /swagger-ui.html
headers={Accept=text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8, Cache-Control=max-age=0, Upgrade-Insecure-Requests=1, User-Agent=Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/70.0.3538.102 Safari/537.36, Connection=keep-alive, If-Modified-Since=Mon, 15 Jan 2018 08:59:31 GMT, Host=127.0.0.1:8181, Accept-Language=zh-CN,zh;q=0.9,en;q=0.8, Accept-Encoding=gzip, deflate, br}
java.lang.Exception: Not Found
	at com.openplatform.api.web.ErrorInfoBuilder.getError(ErrorInfoBuilder.java:133)

未集成其樣式致使的

2018-12-04 17:16:35.081|WARN ||o.s.w.s.PageNotFound|No mapping found for HTTP request with URI [/webjars/springfox-swagger-ui/springfox.js] in DispatcherServlet with name 'dispatcherServlet'
2018-12-04 17:16:35.082|ERROR||c.o.a.w.ErrorInfoBuilder|api error /webjars/springfox-swagger-ui/springfox.js
headers={Accept=*/*, Connection=keep-alive, User-Agent=Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/70.0.3538.102 Safari/537.36, Referer=http://127.0.0.1:8181/swagger-ui.html, Host=127.0.0.1:8181, Accept-Language=zh-CN,zh;q=0.9,en;q=0.8, Accept-Encoding=gzip, deflate, br}
java.lang.Exception: Not Found

解決辦法：

@Override
	public void addResourceHandlers(ResourceHandlerRegistry registry) {
		//swagger靜態頁面和樣式加載
		registry.addResourceHandler("swagger-ui.html")
				.addResourceLocations("classpath:/META-INF/resources/");
		registry.addResourceHandler("/webjars/**")
				.addResourceLocations("classpath:/META-INF/resources/webjars/");
	}

二、版本衝突

Caused by: java.lang.NoSuchMethodError: com.google.common.collect.FluentIterable.concat(Ljava/lang/Iterable;Ljava/lang/Iterable;)Lcom/google/common/collect/FluentIterable;
	at springfox.documentation.schema.DefaultModelDependencyProvider.dependentModels(DefaultModelDependencyProvider.java:79)

報如上錯誤，則確定是版本不兼容，簡單的辦法則是經過看相互依賴找到問題，或者直接修改成統一版本，問題則迎刃而解。
注：swagger 2.7.0確實有不少問題，你們能夠略過這個版本。

四 TOKEN機制優化

對於Restful風格的接口，身份信息都是放在請求頭中，經過攔截器來讀取Header中的Token信息進行身份驗證，可是咱們在Swagger中怎麼設置請求頭參數，咱們須要在每個方法的中都加一個Header參數嗎？固然不是。Swagger中的ParameterBuilder能夠爲咱們全部的接口文檔加上Token參數。想加幾個驗證參數限制均可以。
修改swaggerConfig的方法，添加token參數：

@Bean
	public Docket createRestApi() {
		//token和APPID參數傳入配置
		List<Parameter> pars = new ArrayList<>();
		ParameterBuilder tokenPar = new ParameterBuilder();
		//參數名稱
		tokenPar.name("Authorization")
				//參數默認值
				.defaultValue("")
				//參數描述
				.description("令牌")
				//類型
				.modelRef(new ModelRef("string")).parameterType("header").required(false).build();
		ParameterBuilder appIdPar = new ParameterBuilder();
		appIdPar.name("x-app-id")
				.defaultValue("10001")
				.description("appID")
				.modelRef(new ModelRef("string")).parameterType("header").required(false).build();
		pars.add(tokenPar.build());
		pars.add(appIdPar.build());
		return new Docket(DocumentationType.SWAGGER_2)
				.select()
				.apis(RequestHandlerSelectors.basePackage("com.openplatform.api.controller"))
				.paths(PathSelectors.any())
				.build()
				.globalOperationParameters(pars)
				.apiInfo(apiInfo());
	}

五 swagger頁面樣式
樣式的展現和swagger的版本有直接關係，個人版本是2.8.0,因此以下的頁面樣式是2.8.0版本的效果。

token機制部分截圖：
默認都是沒必要傳的，是否須要傳入參數是經過項目攔截斷定的。

以上幾點就是腿swagger配置的基本流程以及一點心得，swagger的出現非常方便了咱們測試環境的使用，可是對於生產環境而言，確是一種危險。因此下篇則主要介紹生產環境如何禁用swagger。