使用knife4j生成接口文档

第一步

导入 knife4j 的maven坐标 ,在pom.xml中添加依赖

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

第二步 

  在配置类中加入 knife4j 相关配置  (注意修改docket中apis的包名)

@Configuration
@Slf4j
public class WebMvcConfiguration extends WebMvcConfigurationSupport {

@Bean
public Docket docket1() {
    log.info("准备生成接口文档");
    ApiInfo apiInfo = new ApiInfoBuilder()
            .title("苍穹外卖项目接口文档")
            .version("2.0")
            .description("苍穹外卖项目接口文档")
            .build();
    Docket docket = new Docket(DocumentationType.SWAGGER_2)
            .groupName("管理端接口")
            .apiInfo(apiInfo)
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.sky.controller.admin"))
            .paths(PathSelectors.any())
            .build();
    return docket;
}

@Bean
public Docket docket2() {
    log.info("准备生成接口文档");
    ApiInfo apiInfo = new ApiInfoBuilder()
            .title("苍穹外卖项目接口文档")
            .version("2.0")
            .description("苍穹外卖项目接口文档")
            .build();
    Docket docket = new Docket(DocumentationType.SWAGGER_2)
            .groupName("用户端接口")
            .apiInfo(apiInfo)
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.sky.controller.user "))
            .paths(PathSelectors.any())
            .build();
    return docket;
}
/**
 * 设置静态资源映射
 *
 * @param registry
 */
protected void addResourceHandlers(ResourceHandlerRegistry registry) {
    log.info("开始设置静态资源映射");
    registry.addResourceHandler("/doc.html").addResourceLocations("classpath:/META-INF/resources/");
    registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
}
}

 第三步

 访问地址:http://localhost:8080/doc.html   (我的端口是8080)

<think>好的,我现在要解决用户提出的Knife4j生成接口文档时出现请求异常的问题。用户已经提供了一些相关的引用内容,我需要先仔细分析这些信息,然后结合自己的知识,给出解决方案。 首先,用户的问题是关于Knife4j请求异常,尤其是在升级到Spring Boot 3后可能出现的问题。根据引用[2],用户提到在Spring Boot 3下,Knife4j可能无法正常使用,参考了相关的博客文章。这可能涉及版本兼容性问题,因为Spring Boot 3可能引入了一些变更,导致旧版本的Knife4j无法正常工作。 接下来,我需要检查用户可能的配置是否正确。根据引用[3],Knife4j需要正确的包结构和配置类。用户是否正确配置了Knife4j的依赖和Swagger注解?例如,是否添加了@EnableOpenApi或@EnableKnife4j注解?另外,引用[1]强调必须正确添加相关注解,如@Api、@ApiOperation等,否则文档无法完整展示。所以,用户需要检查控制器和接口方法上的注解是否齐全。 另外,引用[5]提到Knife4j与Spring Boot的深度整合,需要正确的starter依赖。可能用户使用Knife4j版本不支持Spring Boot 3,需要升级到兼容的版本。例如,Knife4j 4.x版本可能支持Spring Boot 3,而旧版本如3.x可能不支持。用户需要确认依赖是否正确,比如使用knife4j-openapi3-jakarta-starter。 此外,引用[2]提到的解决方案可能涉及路径配置,比如检查Spring Boot 3是否更改了静态资源的路径,导致Knife4j接口文档无法访问。用户需要确认应用程序的上下文路径是否正确,或者是否存在安全拦截器拦截了相关请求。 总结可能的解决步骤:1. 检查依赖版本是否兼容Spring Boot 3;2. 确认配置类是否正确启用了Knife4j;3. 确保接口和参数注解完整;4. 检查路径配置和静态资源处理;5. 查看日志排除其他异常。 现在需要将这些步骤结构化,用清晰的中文回答,并引用相关引用内容支持。同时生成相关问题,如版本兼容性、注解使用、配置优化等。</think>### Knife4j生成接口文档请求异常解决方案 #### 1. 检查依赖版本兼容性 当使用Spring Boot 3时,必须使用支持Jakarta EE规范的Knife4j版本。例如: ```xml <dependency> <groupId>com.github.xiaoymin</groupId> <artifactId>knife4j-openapi3-jakarta-starter</artifactId> <version>4.3.0</version> </dependency> ``` 旧版本依赖如`knife4j-spring-boot-starter`在Spring Boot 3中会因包路径变更(javax→jakarta)导致类加载失败[^2]。 #### 2. 确认配置类注解 需在配置类中添加`@EnableOpenApi`或`@EnableKnife4j`注解,并配置Docket Bean: ```java @Configuration @EnableOpenApi //Spring Boot 3需使用此注解 public class Knife4jConfig { @Bean public Docket api() { return new Docket(DocumentationType.OAS_30) .apiInfo(apiInfo()) .select() .apis(RequestHandlerSelectors.basePackage("com.example.controller")) .paths(PathSelectors.any()) .build(); } } ``` 若未正确配置包扫描路径,会导致接口无法被识别[^3]。 #### 3. 验证接口注解完整性 每个Controller需添加`@Tag`,接口方法需添加`@Operation`: ```java @Tag(name = "用户管理模块") @RestController public class UserController { @Operation(summary = "用户登录") @PostMapping("/login") public Response login(@RequestBody LoginRequest request) { //... } } ``` 参数需标注`@Parameter`,DTO类字段需添加`@Schema`,否则文档会缺失关键信息[^1][^4]。 #### 4. 排查路径冲突问题 检查是否因以下原因导致资源拦截: - Spring Security未放行Knife4j路径: ```java http.authorizeRequests() .antMatchers("/doc.html", "/webjars/**", "/v3/api-docs/**").permitAll(); ``` - 应用程序上下文路径(server.servlet.context-path)与文档路径冲突 - 静态资源映射配置覆盖了接口文档路径[^5] #### 5. 查看启动日志 重点关注以下异常类型: - `java.lang.NoClassDefFoundError`:依赖版本不兼容 - `Failed to start bean 'documentationPluginsBootstrapper'`:Spring Boot 3与Swagger冲突 - `404 on /v3/api-docs`:接口扫描配置错误 #### 6. 离线文档导出验证 通过访问`http://localhost:8080/doc.html#/home`确认基础功能正常,再使用导出功能测试HTML/PDF生成能力,可辅助判断异常范围[^5]。
评论
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值