更轻量级的的Knf4j接口文档配置实战
什么是Knife4j？
Knife4j是一个为Java MVC框架集成Swagger生成API文档的增强解决方案，其前身是swagger-bootstrap-ui。相比于原生的Swagger，Knife4j不仅提供了更加符合现代开发者使用习惯和审美的Web页面，还通过补充一些注解扩展了Swagger的功能。Knife4j以其小巧、轻量且功能强大的特点，成为了接口文档管理的优选工具。
核心功能
文档说明：
-
Knife4j能够详细列出接口文档的说明，包括接口地址、请求类型、请求示例、请求参数、响应示例、响应参数、响应码等信息。这些信息帮助开发者快速理解和使用API。
在线调试：
-
提供在线接口联调功能，自动解析当前接口参数，返回接口响应内容、headers、响应时间、响应状态码等信息。这一功能极大地方便了开发者在开发过程中进行接口调试。
接口搜索：
提供强大的接口搜索功能，支持按接口地址、请求方法、接口描述等关键字进行搜索。这使得在大型项目中快速定位特定接口变得轻而易举。
接口过滤：
-
提供接口过滤功能，可以根据接口分组、接口标签、接口地址等条件进行过滤。这一功能在管理大量接口时尤为有用。
自定义主题：
-
支持自定义主题，开发者可以根据项目需求定制个性化的API文档界面，提升用户体验。
丰富的扩展功能：
-
如接口排序、接口分组、接口标签等，进一步丰富了API文档管理的功能，使得文档更加结构化和易于管理。
依赖配置
在Spring Boot项目中，可以通过Maven引入Knife4j的依赖：
<!-- knife4j 依赖，接口文档工具 -->
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
<version>4.4.0</version>
</dependency>配置类
通过配置类Knife4jConfig，可以自定义OpenAPI的信息，包括API的标题、版本、描述、服务条款、许可证以及作者信息等。
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Contact;
import io.swagger.v3.oas.models.info.Info;
import io.swagger.v3.oas.models.info.License;
import lombok.extern.slf4j.Slf4j;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
@Slf4j
@Configuration
public class Knife4jConfig {
@Bean
public OpenAPI customOpenAPI() {
return new OpenAPI()
.info(new Info()
.title("网盘系统 API")
.version("1.0")
.description("网盘系统")
.termsOfService("http://192.168.19.120")
.license(new License().name("Apache 2.0")
.url("https://www.baidu.com"))
// 添加作者信息
.contact(new Contact()
.name("hoo") // 替换为作者的名字
.email("") // 替换为作者的电子邮件
.url("") // 替换为作者的网站或个人资料链接
)
) ;
}
}接口示例
以下是一个使用Knife4j注解的接口示例，展示了如何通过Knife4j生成详细的API文档。
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.*;
import java.util.List;
@RestController
@RequestMapping("/api/file/v1")
@Tag(name = "文件管理接口", description = "提供文件和文件夹的管理功能")
public class AccountFileController {
@Autowired
private AccountFileService accountFileService;
@GetMapping("list")
@Operation(summary = "查询文件列表", description = "根据父文件夹ID查询文件列表")
public JsonData list(
@Parameter(description = "父文件夹ID", required = true, example = "1") @RequestParam(value = "parent_id") Long parentId) {
Long accountId = LoginInterceptor.threadLocal.get().getId();
List<AccountFileDTO> list = accountFileService.listFile(accountId, parentId);
return JsonData.buildSuccess(list);
}
}访问地址
配置完成后，可以通过以下地址访问生成的API文档：
访问地址:http://{ip}:{port}/doc.html