苍穹外卖报错-Knife4j文档请求异常解决方式【一篇搞定】

潜意识Java

已于 2025-03-18 09:56:34 修改

阅读量2.4k

点赞数 97

分类专栏： bug 文章标签： maven java servlet spring boot

于 2025-03-13 23:06:47 首次发布

本文链接：https://blog.csdn.net/weixin_73355603/article/details/146244282

版权

bug 专栏收录该内容

3 篇文章

订阅专栏

一.报错形式

Knife4j文档请求异常，图片如图所示

二.为什么会报错

只要是苍穹外卖报错都是版本不兼容的问题，依赖要换版本才可以，其他报错的概率很低，所以认真看！

三.解决方案

3.1去掉原来的依赖

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <version>3.0.2</version>
</dependency>

3.2改成新版的依赖

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
    <version>4.5.0</version>
</dependency>

我试过了，两个依赖不可以同时出现，不然也会报错

四.创建一个包和一个类

五. 复制下面代码到类WebMvcConfiguration

/**
 * 配置类，注册web层相关组件
 */
@Configuration
public class WebMvcConfiguration extends WebMvcConfigurationSupport {

    /**
     * 通过knife4j生成接口文档
     * @return
     */
    @Bean
    public Docket docket() {
        System.out.println("准备生成接口文档..");
        ApiInfo apiInfo = new ApiInfoBuilder()
                .title("苍穹外卖项目接口文档")
                .version("2.0")
                .description("苍穹外卖项目接口文档")
                .build();
        Docket docket = new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo)
                .select()
                .apis(RequestHandlerSelectors.basePackage("idea_students.controller"))
                .paths(PathSelectors.any())
                .build();
        return docket;
    }

    /**
     * 设置静态资源映射
     * @param registry
     */
    protected void addResourceHandlers(ResourceHandlerRegistry registry) {
        System.out.println("开始进行静态资源映射...");
        registry.addResourceHandler("/doc.html").addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
    }
}

六. 修改路径

七. 修改你项目的基本信息

八. 结果

然后访问路径：http://localhost:8080/doc.html

如果访问成功那么解决

九. 总结

Knife4j 作为一款基于 Swagger 的增强工具，在 API 开发、文档管理和团队协作中展现出显著优势。其核心价值体现在以下多个方面：

1. 界面交互与用户体验优化
Knife4j 对原生 Swagger UI 进行了深度重构，采用响应式布局和现代化设计，支持深色模式和动态加载，提升开发者使用舒适度。分栏式导航结构实现 API 分类与接口详情的实时联动，结合智能搜索和书签功能，大幅缩短接口定位时间。内置的接口测试模块支持参数自动填充、请求头管理和响应结果高亮展示，减少测试工具切换频率，提高调试效率。

2. 自动化文档生成与维护
通过注解驱动（如@Api、@ApiOperation）实现零侵入式文档生成，自动提取接口描述、参数、响应等信息，避免手动编写 Markdown 的繁琐。支持多环境配置（开发 / 测试 / 生产），可动态切换文档内容，确保敏感信息不泄露。文档版本管理功能记录 API 迭代历史，便于团队追踪变更。

3. 开发效率提升
集成代码生成功能，支持 Java、TypeScript 等多语言客户端代码生成，降低跨端开发成本。与 Spring Boot 深度整合，通过knife4j-spring-boot-starter实现自动配置，开箱即用。内置离线文档导出功能，支持 HTML/PDF 格式，满足线下交付需求。

4. 团队协作支持
提供评论系统和权限控制，开发者可在文档中直接标注问题或建议，同时支持细粒度的接口访问权限划分。结合 Spring Boot Actuator，可统计 API 调用频率、响应时间等指标，为系统优化提供数据支持。

5. 多协议与扩展性
完全兼容 OpenAPI 3.0 规范，支持与 Postman、Apifox 等工具的数据互导。通过自定义扩展点，可集成企业级认证（如 OAuth2）、请求签名等功能。Markdown 扩展允许在接口描述中嵌入表格、代码块等富文本内容。

6. 企业级安全与合规
提供文档水印、操作日志审计等功能，满足金融、医疗等行业的合规要求。支持 API 请求签名和敏感数据脱敏，有效防范接口滥用。通过 CORS 配置和 Spring Security 集成，保障跨域请求安全。

7. 性能与稳定性
采用轻量化设计，优化接口数据渲染逻辑，支持百万级接口文档流畅展示。异常处理机制提供友好的错误提示和修复建议，确保服务不可用时仍可展示静态缓存文档。

8. 生态整合能力
与 Spring Cloud、Dubbo 等微服务框架无缝对接，支持分布式系统下的 API 管理。通过插件机制扩展功能（如监控集成、第三方登录），适配不同企业需求。

在实际应用中，Knife4j 通过降低文档维护成本、提升接口开发透明度、增强团队协作效率，为企业节省大量人力物力。其灵活性和扩展性使其适用于从单体应用到复杂微服务架构的全场景，成为现代 API 开发中不可或缺的工具。