SpringBoot3.4.3集成Knife4j实现接口文档管理和调试

itbeien2025年3月3日大约 8 分钟

SpringBoot3.4.3集成Knife4j实现接口文档管理和调试

本专栏前一篇文章SpringBoot3.4.3实现文件上传和全局异常处理。今天分享SpringBoot3.4.3集成Knife4j实现接口文档管理和调试功能，让开发者能更高效地进行接口文档的查看、调试等操作。

完整代码在文章最后，如果觉得本篇文章对你有用，记得点赞、关注、收藏哦。你的支持是我持续更新的动力!

文章最后可以加入免费的Java&AI技术和支付系统沟通社群，一起探讨Java/你的产品如何与AI结合，请按照要求加入。在群中可以聊开发、系统设计、架构、行业趋势、AI等等话题

SpringBoot3专栏软件环境

JDK17.0.12
SpringBoot3.4.3
IDEA2024.3.3
knife4j-openapi3-jakarta-spring-boot-starter4.5.0

我们先看本篇文章对应的项目结构，请看下图

1 什么是Knife4j

Knife4j是一个集Swagger2 和 OpenAPI3 为一体的增强解决方案，帮助开发者快速聚合使用OpenAPI规范.

官方网站 https://doc.xiaominfo.com/

1.1 主要功能

接口文档展示：能够将 Swagger 生成的接口信息以更美观、易读的界面呈现出来。它会把接口的详细信息，如接口地址、请求方式、请求参数、响应参数等清晰地展示给开发者，方便查看和理解。
离线文档导出：支持将接口文档导出为多种格式，如 HTML、Markdown 等。这使得开发者可以在没有网络的情况下查看接口文档，也便于将文档分享给其他人员。
在线调试：提供在线调试功能，开发者可以直接在文档页面上对接口进行测试。输入请求参数，点击发送请求，即可查看接口的响应结果，方便快速验证接口的正确性。
增强 UI 界面：对 Swagger 默认的 UI 界面进行了优化，界面更加美观、简洁，操作也更加便捷。同时，支持主题切换，可根据个人喜好选择不同的界面风格。
分组管理：可以对接口进行分组管理，将不同模块或功能的接口归类到不同的分组中，使文档结构更加清晰，便于查找和管理。

1.2 应用场景

前后端分离开发：在前后端分离的项目中，前端开发人员可以通过 Knife4j 提供的接口文档，清晰地了解后端接口的信息，进行接口对接和调试，提高开发效率。
团队协作开发：团队成员之间可以通过共享接口文档，快速了解项目中各个接口的情况，减少沟通成本，提高协作效率。
项目维护：在项目维护阶段，开发人员可以通过查看接口文档，快速了解接口的功能和使用方法，方便对接口进行修改和优化。

1.3 框架适配

适配兼容Spring MVC
适配兼容Spring Boot 2.x、3.x
适配兼容Spring WebFlux
基于SpringFox2.x版本提供Swagger2规范的增强扩展
基于Springdoc-openapi项目提供OAS3规范的增强扩展

1.4 社区生态

基于Servlet体系的微服务聚合中间件Knife4jAggregation
基于Spring Cloud Gateway网关聚合的微服务聚合中间件
独立运行的中间件Knife4jDesktop

1.5 云原生支持

提供基于K8S+Docker的云原生的聚合OpenAPI文档的解决方案
简化Knife4j的使用及学习成本，一键部署&集成&使用

1.6 架构

2 项目集成Knife4j

2.1 pom依赖

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <parent>
        <groupId>cn.itbeien</groupId>
        <artifactId>springboot3-labs-master</artifactId>
        <version>1.0-SNAPSHOT</version>
    </parent>

    <artifactId>springboot-knife4j</artifactId>

    <properties>
        <knife4j-openapi3-jakarta-spring-boot-starter>4.5.0</knife4j-openapi3-jakarta-spring-boot-starter>
    </properties>

    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
        </dependency>
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
            <version>${knife4j-openapi3-jakarta-spring-boot-starter}</version>
        </dependency>
    </dependencies>

</project>

2.2 代码实现

package cn.itbeien.knife4j.controller;


import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.Parameters;
import io.swagger.v3.oas.annotations.enums.ParameterIn;
import io.swagger.v3.oas.annotations.tags.Tag;
import lombok.extern.slf4j.Slf4j;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;

/**
 * @author itbeien
 * 项目网站：https://www.itbeien.cn
 * 公众号：贝恩聊架构
 * 全网同名，欢迎小伙伴们关注
 * Java/AI学习社群
 * Copyright© 2025 itbeien
 */
@RestController
@Tag(name = "测试控制类")
@Slf4j
public class TestController {
    @Operation(summary = "普通请求")
    @PostMapping("/test")
    public ResponseEntity<String> test(@RequestBody String json){
        return ResponseEntity.ok(json);
    }

    @Operation(summary = "普通请求+Param+Header+Path")
    @Parameters({
            @Parameter(name = "id",description = "id",in = ParameterIn.PATH),
            @Parameter(name = "token",description = "请求token",required = true,in = ParameterIn.HEADER),
            @Parameter(name = "name",description = "文件名称",required = true,in=ParameterIn.QUERY)
    })
    @PostMapping("/test/{id}")
    public ResponseEntity<String> test(@PathVariable("id") String id, @RequestHeader("token") String token, @RequestParam("name")String name, @RequestBody String json){
        log.info("name:"+name+",token:"+token+",id:"+id);
        return ResponseEntity.ok(json);
    }
}

2.3 配置信息

springdoc.swagger-ui.path=/swagger-ui.html
springdoc.swagger-ui.tags-sorter=alpha
springdoc.swagger-ui.operations-sorter=alpha
springdoc.api-docs.path=/v3/api-docs
springdoc.group-configs[0].group=default
springdoc.group-configs[0].paths-to-match=/**
springdoc.group-configs[0].packages-to-scan=cn.itbeien.knife4j.controller
knife4j.setting.language=zh_cn