前言
SpringBoot整合swagger,使用swagger-bootstrap-ui美化页面。
1、环境配置
1.1、导入依赖包
<dependency> <groupId>io.springfox</groupId> <artifactId>springfox-boot-starter</artifactId> <version>3.0.0</version> </dependency> <dependency> <groupId>com.github.xiaoymin</groupId> <artifactId>swagger-bootstrap-ui</artifactId> <version>1.9.6</version> </dependency>
1.2、在config目录下增加Swagger3Config配置
import org.springframework.beans.BeansException; import org.springframework.beans.factory.config.BeanPostProcessor; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import org.springframework.util.ReflectionUtils; import org.springframework.web.context.request.async.DeferredResult; import org.springframework.web.servlet.mvc.method.RequestMappingInfoHandlerMapping; import springfox.documentation.builders.ApiInfoBuilder; import springfox.documentation.oas.annotations.EnableOpenApi; import springfox.documentation.service.ApiInfo; import springfox.documentation.spi.DocumentationType; import springfox.documentation.spring.web.plugins.Docket; import springfox.documentation.spring.web.plugins.WebMvcRequestHandlerProvider; import java.lang.reflect.Field; import java.util.List; import java.util.stream.Collectors; @EnableOpenApi @Configuration public class Swagger3Config { @Bean public Docket createRestApi(){ return new Docket(DocumentationType.OAS_30) .genericModelSubstitutes(DeferredResult.class) .useDefaultResponseMessages(false) .forCodeGeneration(false) .pathMapping("/") .select() .build() .apiInfo(apiInfo()); } private ApiInfo apiInfo(){ return new ApiInfoBuilder() .title("Swagger3接口文档") .description("前后端分离的接口文档") .version("1.0") .build(); } @Bean public static BeanPostProcessor springfoxHandlerProviderBeanPostProcessor() { return new BeanPostProcessor() { @Override public Object postProcessAfterInitialization(Object bean, String beanName) throws BeansException { if (bean instanceof WebMvcRequestHandlerProvider) { customizeSpringfoxHandlerMappings(getHandlerMappings(bean)); } return bean; } private <T extends RequestMappingInfoHandlerMapping> void customizeSpringfoxHandlerMappings( List<T> mappings) { List<T> copy = mappings.stream().filter(mapping -> mapping.getPatternParser() == null) .collect(Collectors.toList()); mappings.clear(); mappings.addAll(copy); } @SuppressWarnings("unchecked") private List<RequestMappingInfoHandlerMapping> getHandlerMappings(Object bean) { try { Field field = ReflectionUtils.findField(bean.getClass(), "handlerMappings"); field.setAccessible(true); return (List<RequestMappingInfoHandlerMapping>) field.get(bean); } catch (IllegalArgumentException | IllegalAccessException e) { throw new IllegalStateException(e); } } }; } }
1.3、为Swagger3配置ResourceHandlers
含【Swagger3资源配置】、【静态资源配置】
import org.springframework.context.annotation.Configuration; import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry; import org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport; @Configuration public class WebMvcConfig extends WebMvcConfigurationSupport { @Override protected void addResourceHandlers(ResourceHandlerRegistry registry) { //加载public文件夹数据 registry.addResourceHandler("/public/**") .addResourceLocations("classpath:/public/"); //加载static文件夹数据 registry.addResourceHandler("/static/**") .addResourceLocations("classpath:/static/"); // swagger配置 registry.addResourceHandler("doc.html").addResourceLocations("classpath:/META-INF/resources/"); registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/"); } }
2、应用
2.1、@Api 应用在Controller上
tags :API的展示顺序,例如:1. 2. 3. 4.
@Slf4j @Api(value = "用户服务", tags = "1.用户模块") @RestController @CrossOrigin("*") @RequestMapping("/user") public class UserController { } @Slf4j @Api(value = "订单模块", tags = "2.订单模块") @RestController @RequestMapping("/order") public class OrderController { }
2.2、@ApiOperation 应用在Method上
@ApiOperation(value = "获取订单信息") @ApiImplicitParams({ @ApiImplicitParam(name = "pageObj", value = "分页信息", paramType = "query", dataType = "com.hqyj.springbootmybatis.util.PageObj" ) }) @GetMapping("/getOrderList") public HttpResult getCurrentUserOrderList(PageObj pageObj) { log.info("当前查询第几页:{} , 一页数据量:{}" , pageObj.getCurrentPage() , pageObj.getPageSize()); List<Order> list = new ArrayList<>(); return HttpResultGenerator.success(list); }
3、访问
项目路径 + /doc.html : http://localhost/doc.html