SpringBoot集成Swagger2并配置多个包路径扫描
1. 简介
随着现在主流的前后端分离模式开发越来越成熟，接口文档的编写和规范是一件非常重要的事。简单的项目来说，对应的controller在一个包路径下，因此在Swagger配置参数时只需要配置一个包路径即可。但是对于复杂的项目，往往需要分模块开发，因此对应的controller包存在多个，所以需要在Swagger配置参数时需要指定多个包路径扫描。
在一些普遍情况下，分模块开发时由不同的开发小组来完成，为了保证接口文档的风格统一和方便，在公共模块指定统一的配置工具类，其他模块只需要配置自己的模块名称、编码和指定包路径，即可完成接口文档的配置，大大方便管理和开发。
2. 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）
