SprongBoot3整合Knife4j-4.4

前言

本文将详细的介绍如何在sspringboot3项目中整合Knife4j 4.4

Knife4j官网：

Knife4j · 集Swagger2及OpenAPI3为一体的增强解决方案. | Knife4j (xiaominfo.com)

目前项目的兼容性

Knife4j 与各个版本 Spring Boot 的兼容性情况如下：

• Spring Boot 1.5.x~2.0.0：对应 Knife4j 2.0.0 以下版本；
• Spring Boot 2.0-2.2：对应 Knife4j 2.0.0-2.0.6 版本；
• Spring Boot 2.2.x-2.4.0：对应 Knife4j 2.0.6-2.0.9 版本；
• Spring Boot 2.4.0-2.7.x：对应 Knife4j 4.0.0 及以上版本；
• Spring Boot 3.0 及以上：对应 Knife4j 4.0.0 及以上版本。

这意味着我们在springboot3项目需要使用Knife4j 4.0.0 及以上版本

• 第一步在项目中添加依赖

引用Knife4j的starter,Maven坐标如下：

xml

代码解读

复制代码

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

Gradle坐标如下：

scss

代码解读

复制代码

implementation("com.github.xiaoymin:knife4j-openapi3-jakarta-spring-boot-starter:4.4.0")

目前我们讲解将Knife4j-4.4后正常使用，如需要进一步进行配置完全参考springdoc-openapi的项目说明，Knife4j只提供了增强部分，如果要启用Knife4j的增强功能，可以在配置文件中进行开启

当前项目就整合了Knife4j

• 开发接口

现在我们写一个测试接口

java

代码解读

复制代码

@RestController @RequestMapping("employee-info") public class EmployeeInfoController { @GetMapping("/test") public String test(){ return "hello"; } }

接下来我们就启动项目，在网页使用http://ip:port/doc.html即可查看文档

我这里没有更改端口号，tomcat的默认端口号为8080-，所以我们就直接访问http://localhost:8080/doc.html

可以看到目前页面显示为

可以看到Knife4j已经成功扫描到我们的接口了

接下来我们就去测试一下接口是否可以正常跑通

可以看到我们已经成功跑通接口，并成功拿到了后端给我们的返回数据

参考官方文档，我们可以在配置文件里添加部分配置

application.yml

yml

代码解读

复制代码

# springdoc-openapi项目配置 springdoc: swagger-ui: path: /swagger-ui.html tags-sorter: alpha operations-sorter: alpha api-docs: path: /v3/api-docs group-configs: - group: 'default' paths-to-match: '/**' packages-to-scan: com.xiaominfo.knife4j.demo.web # knife4j的增强配置，不需要增强可以不配 knife4j: enable: true setting: language: zh_cn

以下是这些配置的详解

1. SpringDoc OpenAPI 配置:

   • springdoc.swagger-ui.path: 配置 Swagger UI 的访问路径，默认为 /swagger-ui.html。
   • springdoc.swagger-ui.tags-sorter: 配置 Swagger UI 中接口标签的排序方式，这里设置为字母顺序 (alpha)。
   • springdoc.swagger-ui.operations-sorter: 配置 Swagger UI 中接口操作的排序方式，这里设置为字母顺序 (alpha)。
   • springdoc.api-docs.path: 配置 OpenAPI 文档的访问路径，默认为 /v3/api-docs。
   • springdoc.group-configs: 配置 OpenAPI 分组。这里定义了一个名为 "default" 的分组，扫描 com.xiaominfo.knife4j.demo.web 包下的接口，并匹配所有路径 (/**)。

2. Knife4j 配置:

   • knife4j.enable: 开启 Knife4j 增强功能。
   • knife4j.setting.language: 设置 Knife4j 的界面语言为中文 (zh_cn)。

我们知道在配置文件中的配置参数我们都可以通过配置类的方式达到同样的效果

接下来我们就是用配置的方式去实现

Knife4jConfig.java

java

代码解读

复制代码

import org.springframework.context.annotation.Configuration; import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry; import org.springframework.web.servlet.config.annotation.WebMvcConfigurer; @Configuration public class SpringDocConfig implements WebMvcConfigurer { @Override public void addResourceHandlers(ResourceHandlerRegistry registry) { registry.addResourceHandler("/swagger-ui.html") .addResourceLocations("classpath:/META-INF/resources/"); registry.addResourceHandler("/webjars/**") .addResourceLocations("classpath:/META-INF/resources/webjars/"); } // SpringDoc OpenAPI 配置 @Bean public OpenApiCustomizer openApiCustomizer() { return openApi -> { openApi.getPaths().values().stream() .flatMap(pathItem -> pathItem.readOperations().stream()) .forEach(operation -> operation.addTagsItem("default")); openApi.setInfo(new Info() .title("API 文档") .version("1.0.0")); openApi.getInfo().getContact() .name("多宝") .email("duobao@example.com"); }; } @Bean public GroupedOpenApi defaultGroupedOpenApi() { return GroupedOpenApi.builder() .group("default") .pathsToMatch("/**") .packagesToScan("com.xiaominfo.knife4j.demo.web") .build(); } // Knife4j 配置 @Bean public KnifeSetting knifeSetting() { KnifeSetting setting = new KnifeSetting(); setting.setLanguage(Language.ZH_CN); return setting; } }

总结

本文详细的讲解了如何在springboot3项目中去引入Knife4j-4.4

希望对你能够有所帮助！！！！