spring boot 整合swagger2(knife4j-UI升級版)

前言

Swagger 是什麼？

• Swagger 是一款RESTFUL接口的、基於YAML、JSON語言的文檔在線自動生成、代碼自動生成的工具。

1.作用：

1. 啓動項目後在線自動生成API文檔
2. 在線高效調試

2.官網：https://swagger.io

knife4j 是什麼？

• 爲Java MVC框架集成Swagger的增強解決方案-前身是 swagger-bootstrap-ui
• swagger-bootstrap-ui是springfox-swagger的增強UI實現，爲Java開發者在使用Swagger的時候，能擁有一份簡潔、強大的接口文檔體驗

1.作用：

1. 接口排序
2. 自定義文檔說明
3. 訪問權限控制
4. 請求參數緩存
5. 調試動態請求參數
6. 文檔說明等

2.官網：https://doc.xiaominfo.com

整合

一、pom.xml 引入 依賴

<!-- swagger2-->
		<dependency>
			<groupId>io.springfox</groupId>
			<artifactId>springfox-swagger2</artifactId>
			<version>2.9.2</version>
			<exclusions>
			    <exclusion>
			        <groupId>io.swagger</groupId>
			        <artifactId>swagger-annotations</artifactId>
			    </exclusion>
			    <exclusion>
			        <groupId>io.swagger</groupId>
			        <artifactId>swagger-models</artifactId>
			    </exclusion>
			</exclusions>
		</dependency>
		
		<!--防止進入swagger頁面報類型轉換錯誤，排除2.9.2中的引用，手動增加1.5.21版本-->
        <dependency>
            <groupId>io.swagger</groupId>
            <artifactId>swagger-annotations</artifactId>
            <version>1.5.21</version>
        </dependency>
        
        <dependency>
            <groupId>io.swagger</groupId>
            <artifactId>swagger-models</artifactId>
            <version>1.5.21</version>
        </dependency>

		<!-- swagger2-UI-->
		<dependency>
			<groupId>io.springfox</groupId>
			<artifactId>springfox-swagger-ui</artifactId>
			<version>2.9.2</version>
		</dependency>
		<dependency>
			<groupId>com.github.xiaoymin</groupId>
			<artifactId>knife4j-spring-boot-starter</artifactId>
			<version>2.0.2</version>
		</dependency>

二、創建swagger配置文件(swaggerConfig.java)

@Configuration // 聲明爲配置文件，讓spring加載
@EnableSwagger2 // 支持swagger2插件配置
@EnableKnife4j
@Import(BeanValidatorPluginsConfiguration.class)
public class Swagger2Config {

	// apiInfo對象主要是設置我們api文檔的標題，描述，訪問的地址，創建者等信息
	@SuppressWarnings("deprecation")
	@Bean
	public ApiInfo apiInfo() {
		return new ApiInfoBuilder()
				.title("濃密秀髮之謙先生的Api接口文檔")
				.description("快速進行Api接口調試")
				.termsOfServiceUrl("127.0.0.1:8080")
				.contact("Qian")
				.version("1.0")
				.build();
	}

	/**
	 * 創建API
	 */
	@Bean
	public Docket createRestApi() {
		return new Docket(DocumentationType.SWAGGER_2)
				// .pathMapping("/dev-api")
				// 用來創建該API的基本信息，展示在文檔的頁面中（自定義展示的信息）
				.apiInfo(apiInfo())
				// 設置哪些接口暴露給Swagger展示
				.select()
				// 掃描所有有註解的api，用這種方式更靈活
				// .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
				// 掃描指定包中的swagger註解
				.apis(RequestHandlerSelectors.basePackage("cn.timer.api"))
				// 掃描所有 .apis(RequestHandlerSelectors.any())
				.paths(PathSelectors.any()).build()
				/* 設置安全模式，swagger可以設置訪問token */
				.securitySchemes(securitySchemes()).securityContexts(securityContexts());
	}

	/**
	 * 安全模式，這裏指定token通過Authorization頭請求頭傳遞
	 */
	private List<ApiKey> securitySchemes() {
		List<ApiKey> apiKeyList = new ArrayList<ApiKey>();
		apiKeyList.add(new ApiKey("Authorization", "Authorization", "header"));
		return apiKeyList;
	}

	/**
	 * 安全上下文
	 */
	private List<SecurityContext> securityContexts() {
		List<SecurityContext> securityContexts = new ArrayList<>();
		securityContexts.add(SecurityContext.builder().securityReferences(defaultAuth())
				.forPaths(PathSelectors.regex("^(?!auth).*$")).build());
		return securityContexts;
	}

	/**
	 * 默認的安全上引用
	 */
	private List<SecurityReference> defaultAuth() {
		AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
		AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
		authorizationScopes[0] = authorizationScope;
		List<SecurityReference> securityReferences = new ArrayList<>();
		securityReferences.add(new SecurityReference("Authorization", authorizationScopes));
		return securityReferences;
	}

}

三、啓動項目,訪問 http://localhost:8089/doc.html (請求的端口看自身情況，我項目配置的是8089)

注意：

API排序需要開啓 增強模式

若無法訪問或訪問後API無法正常顯示，原因有以下幾點：

1. 路徑 http://localhost:8089/doc.html 被攔截
2. 靜態資源被後端攔截，如 js、html等

感謝大家的閱讀，有收穫？希望兄弟姐妹三叔六嬸大姨大媽阿公阿婆來個三連擊，給更多的同學看到這篇文章

你的每一次回眸都是永恆，每一次鼓勵都是我前進的動力，每一次分享都是對我的認可。