SpringBoot 项目集成增强版 Swagger-Knife4j - 附常见问题及解决方案


1 - 引入 Maven 依赖

👇点这里展开代码👇
    <properties>
        <spring-boot.version>2.4.3</spring-boot.version>
        <spring.version>5.3.4</spring.version>
        <mybatis.starter.version>2.0.1</mybatis.starter.version>
        
        <swagger.version>3.0.0</swagger.version>
        <knife4j.version>3.0.3</knife4j.version>
        <slf4j.version>1.7.25</slf4j.version>
        <log4j.version>1.2.17</log4j.version>
    </properties>

    <dependencies>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>${swagger.version}</version>
            <exclusions>
                <exclusion>
                    <groupId>org.springframework</groupId>
                    <artifactId>*</artifactId>
                </exclusion>
            </exclusions>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>${swagger.version}</version>
            <exclusions>
                <exclusion>
                    <groupId>org.springframework</groupId>
                    <artifactId>*</artifactId>
                </exclusion>
            </exclusions>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-boot-starter</artifactId>
            <version>${swagger.version}</version>
            <exclusions>
                <exclusion>
                    <artifactId>guava</artifactId>
                    <groupId>com.google.guava</groupId>
                </exclusion>
            </exclusions>
        </dependency>
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>knife4j-spring-boot-starter</artifactId>
            <version>${knife4j.version}</version>
        </dependency>
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>knife4j-annotations</artifactId>
            <version>${knife4j.version}</version>
        </dependency>

        <!-- 日志框架 -->
        <dependency>
            <groupId>org.slf4j</groupId>
            <artifactId>slf4j-api</artifactId>
            <version>${slf4j.version}</version>
        </dependency>
        <dependency>
            <groupId>log4j</groupId>
            <artifactId>log4j</artifactId>
            <version>${log4j.version}</version>
        </dependency>
    </dependencies>

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<Integer> getDataCount(HttpServletRequest request) { }

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

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

    @ApiOperation(value = "查询数据条数,请求参数有:startTime、endTime,格式:yyyyMMddHHmm")
    public Response<Integer> 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<Object> getDetail(@PathVariable(required = false) String id) { }

为了避免这种情况,可以把这个参数改成 @RequestParam,修改如下:

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

参考资料

https://blog.csdn.net/sanyaoxu_2/article/details/80555328
https://zhuanlan.zhihu.com/p/21353795
https://juejin.cn/post/6844903607414816775
https://www.cnblogs.com/paddix/p/8204916.html
https://juejin.cn/post/6844903993890586632


版权声明

作者:瘦风(https://healchow.com)

出处:博客园-瘦风的南墙(https://www.cnblogs.com/shoufeng)

感谢阅读,公众号 「瘦风的南墙」 ,手机端阅读更佳,还有其他福利和心得输出,欢迎扫码关注🤝

本文版权归博主所有,欢迎转载,但 [必须在页面明显位置标明原文链接],否则博主保留追究相关人士法律责任的权利。

打赏

免责声明!

本站转载的文章为个人学习借鉴使用,本站对版权不负任何法律责任。如果侵犯了您的隐私权益,请联系本站邮箱yoyou2525@163.com删除。



 
粤ICP备18138465号  © 2018-2021 CODEPRJ.COM