• 1 - 引入 Maven 依赖
• 2 - 编写 SwaggerConfig 配置类
• 3 - Swagger 常用注解
• 4 - 启动项目后，访问 Swagger 首页出现 Whitelabel Error Page
• 4 - 踩坑指南
  • 4.1 Controller 中的接口都没有显示
  • 4.2 部分 Controller 中的接口显示不全
  • 4.3 页面调试时，提示“xx参数不能为空”
• 参考资料
• 版权声明

1 - 引入 Maven 依赖

    
        2.4.3
        5.3.4
        2.0.1
        
        3.0.0
        3.0.3
        1.7.25
        1.2.17
    

    
        
            io.springfox
            springfox-swagger2
            ${swagger.version}
            
                
                    org.springframework
                    *
                
            
        
        
            io.springfox
            springfox-swagger-ui
            ${swagger.version}
            
                
                    org.springframework
                    *
                
            
        
        
            io.springfox
            springfox-boot-starter
            ${swagger.version}
            
                
                    guava
                    com.google.guava
                
            
        
        
            com.github.xiaoymin
            knife4j-spring-boot-starter
            ${knife4j.version}
        
        
            com.github.xiaoymin
            knife4j-annotations
            ${knife4j.version}
        

        
        
            org.slf4j
            slf4j-api
            ${slf4j.version}
        
        
            log4j
            log4j
            ${log4j.version}
        
    

2 - 编写 SwaggerConfig 配置类

注意：要把此配置类放置在最外侧，与 SpringBoot 的启动类在同一个包下，不能是子包，否则可能会有一些奇怪的问题。

另外，Swagger 3.x 版本中，使用 EnableOpenApi 注解，而不是 EnableSwagger2 注解。

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.oas.annotations.EnableOpenApi;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

/**
 * Swagger API 文档的配置
 * 集成到 SpringBoot 中时，要放在 SpringBoot 启动类 同级的目录下
 */
@Configuration
@EnableOpenApi
public class Swagger2Config {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .enable(true) // 默认开启
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.healchow.swagger.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("HealChow Swagger Doc")
                .description("更多请关注：《https://healchow.com》")
                .version("1.0")
                .build();
    }

}

3 - Swagger 常用注解

待补充。。。

4 - 启动项目后，访问 Swagger 首页出现 Whitelabel Error Page

@Configuration
@ComponentScan
public class ApplicationConfig extends WebMvcConfigurationSupport implements ServletContextInitializer {

    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        // 下面定义了拦截器，会导致 spring.resources.static-locations 配置失效
        registry.addResourceHandler("/**").addResourceLocations("classpath:/webapp/public/");

        // 配置 knife4j 文档资源的访问路径
        registry.addResourceHandler("doc.html").addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
    }

    @Override
    public void addInterceptors(InterceptorRegistry registry) {
        try {
            // 设置ThreadLocal拦截器
            registry.addInterceptor(threadLocalInterceptor()).addPathPatterns("/**")
                    .excludePathPatterns("/login/**").excludePathPatterns("/");

            super.addInterceptors(registry);
        } catch (Exception e) {
            LOGGER.error("Add ThreadLocal Interceptor error", e);
        }
    }

}

4 - 踩坑指南

4.1 Controller 中的接口都没有显示

在 Controller 类上用注解 @Api(tags = "公共接口（上传/下载）") 标识当前 Controller 的功能， tags 的值包含反斜线，导致接口详情无法显示：

改成 @Api(tags = "公共接口（上传、下载）") 后，显示正常：

4.2 部分 Controller 中的接口显示不全

如果请求参数是 Java 基本类型之外的其他复杂类型，比如 HttpServletRequest，那么就不能用 @ApiImplicitParam 描述参数信息，比如下面这种就不行：

    @ApiOperation(value = "查询数据条数")
    @ApiImplicitParam(name = "request", value = "请求体，参数有：startTime、endTime，格式：yyyyMMddHHmm", required = true)
    public Response getDataCount(HttpServletRequest request) { }

可以在日志中看到，出现了空指针异常，可能是没有指定 dataTypeClass 导致的，有知道原因的同学，感谢留言告诉我呀??

最后删掉 @ApiImplicitParam ，改成下面这种就可以全部显示了：

    @ApiOperation(value = "查询数据条数，请求参数有：startTime、endTime，格式：yyyyMMddHHmm")
    public Response getDataCount(HttpServletRequest request) { }

4.3 页面调试时，提示“xx参数不能为空”

对于路径中的变量（以 @PathVariable 注解标识），即使指定可以不填 required = false，在 Swagger 页面也会显示 id不能为空：

    @GetMapping("/getDetail/{id}")
    @ApiOperation(value = "查询详情")
    @ApiImplicitParam(name = "id", value = "数据ID", dataTypeClass = String.class, required = false)
    public Response