解决Knife4j在SpringBoot中访问doc.html页面404问题

解决Knife4j在SpringBoot中访问doc.html页面404问题

问题背景

在使用Knife4j（原swagger-bootstrap-ui）时，开发者经常会遇到访问doc.html页面返回404错误的情况。这个页面是Knife4j提供的增强版Swagger UI界面，提供了更丰富的文档展示和调试功能。

原因分析

出现404错误通常是由于SpringBoot无法正确找到静态资源文件导致的。Knife4j的静态资源文件（包括doc.html）默认存放在META-INF/resources/目录下，如果SpringBoot没有正确配置资源处理器，就会导致访问失败。

解决方案

基础解决方案

在SpringBoot应用中，我们需要实现WebMvcConfigurer接口并重写addResourceHandlers方法，添加对Knife4j静态资源的支持：

@SpringBootApplication
public class MyApplication implements WebMvcConfigurer {

    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        // 配置doc.html页面
        registry.addResourceHandler("doc.html")
                .addResourceLocations("classpath:/META-INF/resources/");
        
        // 配置webjars资源
        registry.addResourceHandler("/webjars/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/");
    }
}

替代方案

如果你使用的是较老版本的SpringBoot，可能需要通过继承WebMvcConfigurationSupport来实现：

@Configuration
public class WebMvcConfig extends WebMvcConfigurationSupport {
    
    @Override
    protected void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("doc.html")
                .addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/");
        super.addResourceHandlers(registry);
    }
}

注意事项

1. classpath与classpath*的区别：

   • classpath:只会在第一个找到的类路径下查找
   • classpath*:会在所有类路径下查找 大多数情况下使用classpath:即可，除非你的资源文件分布在多个jar包中。

2. 版本兼容性：

   • 对于SpringBoot 2.x版本，推荐使用实现WebMvcConfigurer接口的方式
   • 对于SpringBoot 1.x版本，可能需要使用继承WebMvcConfigurationSupport的方式

调试技巧

如果按照上述配置仍然无法访问，可以开启Spring的Debug日志来排查问题：

logging.level.org.springframework=DEBUG

成功访问doc.html时，日志中应该能看到类似以下信息：

DEBUG - Looking up handler method for path /doc.html
DEBUG - Did not find handler method for [/doc.html]
DEBUG - Mapping [/doc.html] to HandlerExecutionChain with handler [ResourceHttpRequestHandler...]

常见问题排查

1. 使用了权限框架：

   • 如果项目中使用了Shiro、Spring Security等权限框架，需要确保doc.html和相关的静态资源路径没有被拦截
   • 添加相应的权限放行配置

2. 多模块项目：

   • 在多模块项目中，确保Knife4j的依赖已经正确传递到主模块
   • 检查资源文件是否被打包到最终的jar/war中

3. 版本冲突：

   • 确保Knife4j版本与SpringBoot版本兼容
   • 检查是否有其他Swagger相关依赖导致冲突

最佳实践

1. 统一配置方式：

   • 推荐使用实现WebMvcConfigurer接口的方式，而不是继承WebMvcConfigurationSupport
   • 后者会覆盖SpringBoot的默认配置，可能导致其他自动配置失效

2. 配置顺序：

   • 如果有多个配置类，确保资源处理器配置的优先级正确
   • 避免被其他配置覆盖

3. 测试验证：

   • 配置完成后，可以直接访问http://localhost:8080/doc.html测试
   • 也可以通过检查jar包中的META-INF/resources/目录确认资源文件是否存在

通过以上方法，大多数情况下都能解决Knife4j的doc.html页面404问题。如果仍然无法解决，建议检查项目依赖和完整的日志输出，定位具体原因。