Spring Boot 2.7 + JDK8 集成 Knife4j 4.1.0 教程(仅展示带注解接口)

Spring Boot 2.7 + JDK8 集成 Knife4j 4.1.0 教程(仅展示带注解接口)

前言

在 Spring Boot 2.7 + JDK8 开发场景中,Knife4j 是主流的接口文档美化增强工具。本文基于 SpringDoc OpenAPI3 集成 Knife4j 4.1.0 (完美适配 SpringBoot 2.7 + JDK8),实现接口文档自动生成,核心实现:仅展示标注 @Tag/@Operation 注解的接口,自动过滤冗余接口,让文档更简洁规范。


一、引入 Maven 依赖(pom.xml)

Knife4j 4.1.0 为 Spring Boot 2.7 + JDK8 专属适配版本,基于 SpringDoc 1.6.15 开发,一站式 starter 集成,无需额外引入 SpringDoc 依赖:

xml 复制代码
<!-- SpringDoc OpenAPI3 接口文档(JDK8 + SpringBoot 2.7 专用) -->
<!-- Knife4j 4.1.0 增强美化版,完美适配 SpringDoc1.6.15 + SpringBoot2.7 + JDK8 -->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-openapi3-spring-boot-starter</artifactId>
    <version>4.1.0</version>
</dependency>

二、application.yml 核心配置

配置文档基础信息、开启 Knife4j 增强功能,配置项简洁易懂,支持自定义修改:

yaml 复制代码
knife4j:
  # 开启Knife4j增强模式
  enable: true
  # 接口文档基础信息配置
  openapi:
    title: 项目接口文档
    description: 后端API接口规范文档
    email: dev@xxx.com
    concat: 开发组
    version: 1.0.0

三、核心配置类(仅展示带注解的接口)

核心功能 :通过方法过滤器,只显示添加了 @Operation 注解的接口方法 ,无注解的接口自动隐藏;

配置类中已删除冗余未使用代码,直接复制可用,仅需修改包扫描路径:

java 复制代码
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springdoc.core.GroupedOpenApi;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import java.lang.reflect.Method;

/**
 * Knife4j 配置类
 * 功能:仅展示标注 @Tag(类)、@Operation(方法) 注解的接口
 */
@Configuration
public class Knife4jConfig {

    /**
     * 自定义接口分组配置
     */
    @Bean
    public GroupedOpenApi customApi() {
        return GroupedOpenApi.builder()
                .group("所有接口") // 接口分组名称,可自定义
                .packagesToScan("com.example.demo") // 【必填】修改为你的Controller包路径
                // 方法过滤:仅保留标注 @Operation 注解的接口方法
                .addOpenApiMethodFilter(this::isMethodWithOperation)
                .build();
    }

    /**
     * 方法过滤规则
     * 判断接口方法是否标注 @Operation 注解
     * @param method 接口方法
     * @return 有注解返回true,无注解返回false(自动隐藏)
     */
    private boolean isMethodWithOperation(Method method) {
        return method.isAnnotationPresent(Operation.class);
    }
}

四、Controller 接口使用示例

注解规范:

  • @Tag:标注在 Controller 类上,定义接口分组名称和描述
  • @Operation:标注在接口方法上,定义接口名称和描述(必须添加,否则接口不显示)
java 复制代码
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@Tag(name = "用户管理", description = "用户相关业务接口") // 类注解:必填
public class UserController {

    /**
     * 标注@Operation注解:接口会正常显示在文档中
     */
    @GetMapping("/user/list")
    @Operation(summary = "获取用户列表", description = "分页查询系统用户信息") // 方法注解:必填
    public String getUserList() {
        return "用户列表";
    }

    /**
     * 未标注@Operation注解:接口会被过滤,不显示在文档中
     */
    @GetMapping("/user/info")
    public String getUserInfo() {
        return "用户信息";
    }
}

五、文档访问地址

启动项目后,访问 Knife4j 文档地址:

复制代码
http://localhost:你的项目端口/doc.html

总结

  1. 全程适配 Spring Boot 2.7 + JDK8,无版本兼容问题;
  2. 依赖仅需引入一个 Knife4j starter,极简集成;
  3. 精准过滤接口,无注解接口自动隐藏,文档更整洁;
  4. 注解用法简单,零学习成本,快速落地。
相关推荐
码事漫谈2 小时前
当公司不久后变成冒险者公会,我担心什么
后端
星落梦生2 小时前
SpringAOP基础笔记(7)
java·开发语言
金銀銅鐵3 小时前
带您看懂字节码指令(四):一条指令里有什么
java·jvm
Csvn3 小时前
Nginx 负载均衡进阶与健康检查:哈希、keepalive 池与 DNS 自愈
后端·nginx
最强小杰4 小时前
某 OpenAI 兼容网关上的 `kimi-k3.1-pro`:Cline、Zed 接入与 SSE 排错示例
java·服务器·网络·ai
皮皮林5514 小时前
京东又开源一款新框架,用起来真优雅!
后端
Flynn Liang4 小时前
流量治理不是限流那么简单:I/O 密集型 Java 服务的 6 层防线
java·微服务·高并发·限流·熔断·系统稳定性·resilience4j
学长毕设4 小时前
基于SpringBoot智慧养老服务平台设计与实现-附源码
java·spring boot·后端
曹牧5 小时前
Java:“刷新雪崩”
java·开发语言
秋天的怀念_David5 小时前
算法一千零一夜 · 第三十三夜 · 跳表
java·程序人生·算法