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

总结

全程适配 Spring Boot 2.7 + JDK8，无版本兼容问题；
依赖仅需引入一个 Knife4j starter，极简集成；
精准过滤接口，无注解接口自动隐藏，文档更整洁；
注解用法简单，零学习成本，快速落地。