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