SpringBoot集成Swagger2並配置多個包路徑掃描

1. 簡介

  隨着現在主流的前后端分離模式開發越來越成熟，接口文檔的編寫和規范是一件非常重要的事。簡單的項目來說，對應的controller在一個包路徑下，因此在Swagger配置參數時只需要配置一個包路徑即可。但是對於復雜的項目，往往需要分模塊開發，因此對應的controller包存在多個，所以需要在Swagger配置參數時需要指定多個包路徑掃描。
  在一些普遍情況下，分模塊開發時由不同的開發小組來完成，為了保證接口文檔的風格統一和方便，在公共模塊指定統一的配置工具類，其他模塊只需要配置自己的模塊名稱、編碼和指定包路徑，即可完成接口文檔的配置，大大方便管理和開發。

2. Swagger2相關文章

  SpringBoot整合Swagger2詳細教程

3. Swagger配置多個包路徑掃描示例代碼

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

import com.google.common.base.Function;
import com.google.common.base.Optional;
import com.google.common.base.Predicate;

import springfox.documentation.RequestHandler;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
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;

/**
 * Swagger2配置類
 * 
 * @author CL
 *
 */
@Configuration
@EnableSwagger2
public class Swagger2Config {

	/**
	 * 定義分隔符
	 */
	private static final String splitor = ";";

	/**
	 * 注入Docket
	 * 
	 * @return
	 */
	@Bean
	public Docket docket() {
		String basePackages = "com.c3stones.sys.controller" + splitor + "com.c3stones.common.controller";
		return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select().apis(basePackage(basePackages))
				.paths(PathSelectors.any()).build();
	}

	/**
	 * 聲明基礎包
	 * 
	 * @param basePackage 基礎包路徑
	 * @return
	 */
	public static Predicate<RequestHandler> basePackage(final String basePackage) {
		return input -> declaringClass(input).transform(handlerPackage(basePackage)).or(true);
	}

	/**
	 * 校驗基礎包
	 * 
	 * @param basePackage 基礎包路徑
	 * @return
	 */
	private static Function<Class<?>, Boolean> handlerPackage(final String basePackage) {
		return input -> {
			for (String strPackage : basePackage.split(splitor)) {
				boolean isMatch = input.getPackage().getName().startsWith(strPackage);
				if (isMatch) {
					return true;
				}
			}
			return false;
		};
	}

	/**
	 * 檢驗基礎包實例
	 * 
	 * @param requestHandler 請求處理類
	 * @return
	 */
	@SuppressWarnings("deprecation")
	private static Optional<? extends Class<?>> declaringClass(RequestHandler requestHandler) {
		return Optional.fromNullable(requestHandler.declaringClass());
	}

	/**
	 * 配置在線文檔的基本信息
	 * 
	 * @return
	 */
	private static ApiInfo apiInfo() {
		return new ApiInfoBuilder().title("SpringBoot集成Swagger2並配置多個包路徑掃描示例")
				.contact(new Contact("Powered By C3Stones", "https://www.cnblogs.com/cao-lei", null))
				.termsOfServiceUrl("https://www.cnblogs.com/cao-lei/").version("V1.0").build();
	}

}

4. 多模塊分工開發時配置

• 定義公共配置類

import org.springframework.stereotype.Component;
import org.springframework.web.bind.annotation.ResponseBody;

import com.google.common.base.Function;
import com.google.common.base.Optional;
import com.google.common.base.Predicate;
import com.google.common.base.Predicates;

import springfox.documentation.RequestHandler;
import springfox.documentation.builders.ApiInfoBuilder;
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;

/**
 * Swagger2配置工具類
 * 
 * @author CL
 *
 */
@Component
@EnableSwagger2
public class Swagger2ConfigUtils {

	/**
	 * 配置模塊
	 * 
	 * @param moduleCode  模塊Code
	 * @param moduleName  模塊名稱
	 * @param basePackage 基礎包（多個）
	 * @return
	 */
	public static Docket docket(String moduleCode, String moduleName, String... basePackage) {
		return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo(moduleName)).groupName(moduleCode).select()
				.apis(Predicates.and(RequestHandlerSelectors.withMethodAnnotation(ResponseBody.class),
						basePackage(basePackage)))
				.build();
	}

	/**
	 * 聲明基礎包
	 * 
	 * @param basePackage 基礎包路徑
	 * @return
	 */
	public static Predicate<RequestHandler> basePackage(final String... basePackage) {
		return input -> declaringClass(input).transform(handlerPackage(basePackage)).or(true);
	}

	/**
	 * 校驗基礎包
	 * 
	 * @param basePackage 基礎包路徑
	 * @return
	 */
	private static Function<Class<?>, Boolean> handlerPackage(final String... basePackage) {
		return input -> {
			for (String strPackage : basePackage) {
				boolean isMatch = input.getPackage().getName().startsWith(strPackage);
				if (isMatch) {
					return true;
				}
			}
			return false;
		};
	}

	/**
	 * 檢驗基礎包實例
	 * 
	 * @param requestHandler 請求處理類
	 * @return
	 */
	@SuppressWarnings("deprecation")
	private static Optional<? extends Class<?>> declaringClass(RequestHandler requestHandler) {
		return Optional.fromNullable(requestHandler.declaringClass());
	}

	/**
	 * 配置在線文檔的基本信息
	 * 
	 * @return
	 */
	private static ApiInfo apiInfo(String moduleName) {
		return new ApiInfoBuilder().title(moduleName)
				.contact(new Contact("Powered By C3Stones", "https://www.cnblogs.com/cao-lei", null))
				.termsOfServiceUrl("https://www.cnblogs.com/cao-lei/").version("V1.0").build();
	}

}

• 在其他模塊中使用
    例如：核心模塊、商城模塊。

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

import com.c3stones.common.utils.Swagger2ConfigUtils;

import springfox.documentation.spring.web.plugins.Docket;

/**
 * Core模塊Swagger2配置類
 * 
 * @author CL
 *
 */
@Configuration
public class CoreSwagger2Config {

	/**
	 * 新增Core模塊
	 * 
	 * @return
	 */
	@Bean
	public Docket coreApi() {
		String moduleCode = "core";
		String moduleName = "核心模塊";
		String[] basePackage = { "com.c3stones.sys.controller", "com.c3stones.common.controller" };
		return Swagger2ConfigUtils.docket(moduleCode, moduleName, basePackage);
	}

}

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

import com.c3stones.common.utils.Swagger2ConfigUtils;

import springfox.documentation.spring.web.plugins.Docket;

/**
 * Shop模塊Swagger2配置類
 * 
 * @author CL
 *
 */
@Configuration
public class ShopSwagger2Config {

	/**
	 * 新增Shop模塊
	 * 
	 * @return
	 */
	@Bean
	public Docket shopApi() {
		String moduleCode = "shop";
		String moduleName = "商城模塊";
		String basePackage = "com.c3stones.order.controller";
		return Swagger2ConfigUtils.docket(moduleCode, moduleName, basePackage);
	}

}

• 啟動項目

5. 測試

• 瀏覽器訪問

# 因為使用了其他的Swagger UI（https://github.com/xiaoymin/swagger-bootstrap-ui），因此路徑變為/doc.html
# 若使用原生的UI,則請求：http://127.0.0.1:8080/swagger-ui.html

http://127.0.0.1:8080/doc.html

• 截圖（原生UI和新UI）
  
  

6. 項目地址

  spring-boot-swagger2-demo2