【SpringBoot】集成 Knife4j

---

一、Knife4j 核心定位

Knife4j 是一款基于OpenAPI规范（OpenAPI3.0）开发的接口文档工具，核心定位是「接口文档全解决方案」，主打「轻量无冗余、功能强大、UI友好、适配性强」，可独立完成接口文档的生成、调试与交付，适配各类Java后端项目开发需求。

======= 🌟 青柠来相伴，代码更简单。🌟 =======
📚 本文所有内容，我都整理在了 青柠合集 里。👇
🎯 搜索关注【青柠代码录】，即可查看所有合集文章 ~
======= 🌟 =================== 🌟 =======

1.1 核心优势

1. 轻量独立运行：无需冗余依赖，纯Knife4j即可实现全功能，降低项目依赖负担，部署便捷
2. 现代化UI体验：简洁美观，支持深色模式、响应式布局，接口分类清晰，操作流畅，提升团队使用效率
3. 全功能覆盖：支持接口文档自动生成、在线调试、全局参数配置、离线文档导出、接口排序、微服务聚合等核心需求
4. 高版本适配：完美支持SpringBoot 2.x、SpringBoot 3.x，兼容JDK8/11/17，适配单体、微服务、分布式等所有架构
5. 零侵入无耦合：无需修改业务代码，仅通过配置即可生成接口文档，不影响项目原有逻辑
6. 中文友好+社区完善：国人开发，中文文档齐全，社区响应快，解决问题成本低，贴合国内开发习惯
7. 安全可控：支持多环境动态开关、接口权限控制、敏感接口隐藏，满足生产环境安全要求

1.2 适用场景

• 新项目开发，追求轻量、高效的接口文档方案，提升前后端协作效率
• 原有项目接口文档体验不佳，需替换更强大、更易用的文档工具
• 微服务项目，需要统一聚合所有服务接口文档，实现一站式查看与调试
• 有甲方交付、文档归档需求，需要导出规范的离线接口文档（MD/HTML/Word等）
• SpringBoot 3.x项目，需要适配高版本Spring生态的接口文档工具

二、Knife4j 集成

Knife4j 提供两种集成方式：Starter模式（推荐，极简便捷） 和 原生模式（高度自定义），两种方式均能满足不同开发场景需求，下面分别详细讲解，确保新手也能快速上手。

2.1 环境准备

• SpringBoot 版本：2.x（2.7.x及以上推荐）/ 3.x（本文分版本讲解，适配不同需求）
• JDK版本：8+（主流JDK8，JDK11/17均兼容，无额外配置）
• Knife4j版本：3.0.3（稳定版，首选，部署便捷、兼容性强）
• 核心依赖：仅需导入Knife4j专属依赖，配置简单，快速启用

2.2 方式一：Starter 集成（首选）

无需额外复杂配置，仅需导入Knife4j Starter依赖、开启Knife4j注解，即可自动生成接口文档，适合大多数单体应用、微服务子模块，零配置上手，大幅提升开发效率。

步骤1：导入Knife4j Starter依赖

在项目pom.xml中导入Knife4j Starter依赖，无需额外添加其他冗余依赖，适配SpringBoot 2.x版本（3.x版本后续单独讲解）：

<!-- Knife4j Starter 依赖（稳定版，适配SpringBoot 2.x） -->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <version>3.0.3</version>
</dependency>

说明：该依赖已包含Knife4j核心功能、UI界面、接口生成等所有组件，无需额外导入其他包，直接引入即可。

步骤2：开启Knife4j功能（启动类注解）

在SpringBoot启动类上添加@EnableKnife4j注解，开启Knife4j的所有功能，无需其他配置，简单便捷：

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import com.github.xiaoymin.knife4j.spring.annotations.EnableKnife4j;

// 开启Knife4j接口文档功能（核心注解）
@EnableKnife4j
@SpringBootApplication
public class QingNingContentApplication {
    public static void main(String[] args) {
        SpringApplication.run(QingNingContentApplication.class, args);
    }
}

注意：@EnableKnife4j是Knife4j的核心启用注解，必须添加在启动类或配置类上，否则无法启用Knife4j的文档生成、UI展示等功能。

步骤3：配置基础文档信息（可选，规范）

为了让接口文档更规范、更易读，推荐在application.yml（或bootstrap.yml）中配置Knife4j基础信息，如文档标题、描述、版本、联系人等，贴合文档规范：

knife4j:
  # 基础文档配置
  api-info:
    title: 青柠代码录 - 内容管理系统接口文档
    description: 青柠代码录Java全栈实战项目，包含课程管理、内容审核、权限控制等核心接口
    version: 1.0.0
    # 联系人信息（规范，便于前后端、测试沟通）
    contact:
      name: 青柠代码录
      url: https://qingning.com
      email: qingning@163.com
  # 接口扫描配置（默认扫描所有Controller，可自定义）
  scan:
    base-package: com.qingning.content.controller # 扫描Controller所在包路径
    # 排除不需要生成文档的接口路径（可选）
    exclude-path: /error,/health

说明：

• base-package：指定扫描的Controller包路径，确保Knife4j能正确识别接口，生成文档
• exclude-path：排除不需要生成文档的接口（如健康检查、错误页面接口），避免文档冗余
• api-info中的配置会显示在文档首页，提升文档规范性，项目建议必配

步骤4：访问Knife4j文档页面

配置完成后，启动SpringBoot项目，访问Knife4j专属文档地址（固定路径，无需修改）：

http://localhost:端口号/服务上下文/doc.html

示例（青柠代码录内容管理系统，端口63040，上下文/content）：

http://localhost:63040/content/doc.html

访问成功后，即可看到Knife4j的现代化UI界面，所有Controller中的接口会自动生成文档，包含接口名称、请求方式、参数说明、响应示例等信息，无需手动编写。

2.3 方式二：原生集成

高度自定义，微服务推荐

适合需要自定义文档分组、全局参数、接口排序、UI样式等场景，比如微服务多模块、需要区分admin/frontend接口的项目，核心是创建Knife4j配置类，实现个性化配置。

步骤1：导入Knife4j原生依赖

导入Knife4j原生依赖（区别于Starter，可灵活配置组件），适配SpringBoot 2.x版本：

<!-- Knife4j 核心依赖 -->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-core</artifactId>
    <version>3.0.3</version>
</dependency>
<!-- Knife4j Spring 集成依赖 -->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring</artifactId>
    <version>3.0.3</version>
</dependency>
<!-- OpenAPI3 核心依赖（Knife4j基于OpenAPI3规范，必导） -->
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-ui</artifactId>
    <version>1.6.15</version>
</dependency>

步骤2：创建Knife4j配置类（核心，自定义配置）

创建配置类，配置文档分组、全局参数、接口扫描范围、文档信息等，注释详细：

package com.qingning.base.config;

import com.github.xiaoymin.knife4j.spring.annotations.EnableKnife4j;
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 org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
@EnableKnife4j // 开启Knife4j增强功能（核心注解）
public class Knife4jConfig {

    /**
     * 配置OpenAPI信息（文档基础信息）
     */
    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
                // 文档基础信息
                .info(new Info()
                        .title("青柠代码录 - 接口文档总览")
                        .description("青柠代码录Java全栈项目，包含所有模块接口定义，便于前后端协作、测试调试")
                        .version("1.0.0")
                        // 联系人信息
                        .contact(new Contact()
                                .name("青柠代码录")
                                .url("https://qingning.com")
                                .email("qingning@163.com"))
                        // 许可证信息（可选，规范）
                        .license(new License()
                                .name("Apache 2.0")
                                .url("https://www.apache.org/licenses/LICENSE-2.0.html")));
    }

    /**
     * 配置admin接口分组（微服务常用，区分不同模块接口）
     */
    @Bean
    public GroupedOpenApi adminGroup() {
        // 扫描admin模块的Controller，路径匹配/api/admin/**
        return GroupedOpenApi.builder()
                .group("admin-api") // 分组名称（文档左侧显示）
                .pathsToMatch("/api/admin/**") // 接口路径匹配
                .packagesToScan("com.qingning.content.controller.admin") // 扫描的包路径
                .build();
    }

    /**
     * 配置frontend接口分组（前端用户接口）
     */
    @Bean
    public GroupedOpenApi frontendGroup() {
        return GroupedOpenApi.builder()
                .group("frontend-api")
                .pathsToMatch("/api/frontend/**")
                .packagesToScan("com.qingning.content.controller.frontend")
                .build();
    }
}

关键说明

• GroupedOpenApi：用于配置接口分组，微服务项目建议按模块分组（admin/frontend），方便前端、测试区分接口，提升协作效率
• OpenAPI：配置文档全局信息，包含标题、描述、版本、联系人等，符合文档规范
• pathsToMatch + packagesToScan：精准控制每个分组扫描的接口路径和包，避免接口混乱

2.4 SpringBoot 3.x 集成方案

SpringBoot 3.x 对依赖版本要求较高，需使用Knife4j适配3.x的专属依赖，集成步骤如下（极简版）：

步骤1：导入SpringBoot 3.x 专属依赖

<!-- Knife4j OpenAPI3 Starter（适配SpringBoot 3.x） -->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-openapi3-spring-boot-starter</artifactId>
    <version>3.0.3</version>
</dependency>

步骤2：开启Knife4j并配置基础信息

启动类添加@EnableKnife4j注解，application.yml配置文档信息（与2.x版本一致）：

@EnableKnife4j
@SpringBootApplication
public class QingNingContentApplication {
    public static void main(String[] args) {
        SpringApplication.run(QingNingContentApplication.class, args);
    }
}
knife4j:
  api-info:
    title: 青柠代码录 - 内容管理系统接口文档
    description: 适配SpringBoot 3.x版本，包含课程管理、权限控制等核心接口
    version: 1.0.0
    contact:
      name: 青柠代码录
      url: https://qingning.com
      email: qingning@163.com
  scan:
    base-package: com.qingning.content.controller

步骤3：访问文档

访问地址与2.x版本一致：http://localhost:端口号/服务上下文/doc.html，无需额外修改。

三、Knife4j 核心功能

Knife4j 提供丰富的功能，覆盖接口文档生成、在线调试、离线导出等核心场景，下面详细讲解每个功能的使用方法，贴合实际开发需求。

3.1 接口文档自动生成

Knife4j 会自动扫描Controller中的接口，生成规范的接口文档，无需手动编写，只需在Controller、方法、实体类上添加简单注解，即可完善文档信息。

注解是规范Knife4j文档的核心，下面详细讲解所有常用注解的用法、属性、场景。

3.2 Knife4j 常用注解详解

Knife4j 基于OpenAPI3规范，所有常用注解均围绕「接口文档规范化」设计，涵盖Controller、接口方法、参数、实体类等所有场景。

3.2.1 @EnableKnife4j（核心启用）

注解说明：Knife4j的核心启用注解，用于开启Knife4j的所有功能（文档生成、UI展示、在线调试、离线导出等），无此注解则Knife4j无法生效，是所有集成方式的必备注解。

核心属性：无额外属性，仅作为启用标识。

使用场景：添加在SpringBoot启动类或Knife4j配置类上，全局生效，只需添加一次即可。

完整示例：

// 方式1：添加在启动类（推荐，简洁直观）
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import com.github.xiaoymin.knife4j.spring.annotations.EnableKnife4j;

@EnableKnife4j // 开启Knife4j所有功能
@SpringBootApplication
public class QingNingContentApplication {
    public static void main(String[] args) {
        SpringApplication.run(QingNingContentApplication.class, args);
    }
}

// 方式2：添加在配置类（适合配置复杂的场景）
@Configuration
@EnableKnife4j
public class Knife4jConfig {
    // 配置内容...
}

注意事项：SpringBoot 2.x和3.x版本通用，无需区分；若未添加该注解，访问doc.html页面会提示404或无法显示接口文档。

3.2.2 @Tag（Controller模块）

注解说明：用于描述整个Controller类的功能，相当于「接口模块分组」，在Knife4j文档左侧显示为一级菜单，方便开发者、测试人员区分不同模块的接口（如课程管理、用户管理）。

核心属性：

• name（必填）：模块名称，简洁明了，如「课程管理接口」「用户权限接口」，将显示在文档左侧菜单。
• description（可选）：模块详细描述，说明该模块的核心功能，如「包含课程基础信息增删改查、审核、发布等接口」。
• tags（可选）：额外标签，用于对模块进行分类，多模块聚合时可用于筛选，一般开发无需使用。

使用场景：添加在Controller类上，每个Controller类建议添加，确保接口分组清晰，尤其适合微服务多模块项目。

完整示例：

import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.web.bind.annotation.RestController;
import org.springframework.web.bind.annotation.RequestMapping;

// 模块名称清晰，描述详细，贴合规范
@Tag(name = "课程管理接口", description = "包含课程基础信息、审核、发布、删除等核心接口，支持分页查询、详情查询")
@RestController
@RequestMapping("/course")
public class CourseBaseInfoController {
    // 接口方法...
}

规范：name属性建议统一格式「模块名称+接口」，description属性明确该模块的接口范围，避免模糊表述（如不建议只写「课程接口」）。

3.2.3 @Operation（接口方法）

注解说明：用于描述单个接口方法的功能，是最常用的注解之一，在Knife4j文档中显示为接口名称和详细说明，是前后端联调、测试调试的核心参考。

核心属性：

• summary（必填）：接口简要名称，简洁明了，如「课程分页查询接口」「根据ID删除课程」，一眼能看出接口功能。
• description（可选）：接口详细描述，说明接口的功能、参数含义、返回值说明、异常情况等，如「支持按课程名称、审核状态模糊筛选，分页返回课程列表，未传筛选条件则返回所有课程」。
• hidden（可选，默认false）：是否隐藏该接口，true表示不生成到文档中，适合敏感接口（如数据删除、权限修改），避免泄露。
• method（可选，默认自动识别）：指定接口请求方式（GET/POST/PUT/DELETE），一般无需手动指定，Knife4j会自动识别@RequestMapping、@GetMapping等注解的请求方式。
• parameters（可选）：用于手动指定接口参数，一般无需使用，推荐使用@Parameter注解单独描述参数。

使用场景：添加在每个接口方法上，无论是GET、POST还是其他请求方式，都建议添加，确保每个接口的功能清晰可查。

完整示例：

import io.swagger.v3.oas.annotations.Operation;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;

@RestController
@RequestMapping("/course")
@Tag(name = "课程管理接口", description = "包含课程基础信息增删改查等接口")
public class CourseBaseInfoController {

    // 普通接口示例（分页查询）
    @Operation(
            summary = "课程分页查询接口",
            description = "支持按课程名称（模糊匹配）、审核状态（UNREVIEWED/REVIEWED）筛选，分页返回课程列表；" +
                    "未传筛选条件则返回所有课程，分页参数默认页码1、每页10条"
    )
    @PostMapping("/list")
    public PageResult<CourseBase> queryCourseList(
            @RequestBody PageParams pageParams,
            @RequestBody QueryCourseParamsDto dto
    ) {
        return courseService.queryPage(pageParams, dto);
    }

    // 敏感接口示例（隐藏接口）
    @Operation(
            summary = "删除课程接口",
            description = "传入课程ID，逻辑删除课程（并非物理删除），仅管理员可调用",
            hidden = true // 隐藏该接口，不生成到文档中
    )
    @PostMapping("/delete/{id}")
    public Result deleteCourse(@PathVariable Long id) {
        courseService.delete(id);
        return Result.success();
    }
}

3.2.4 @ApiOperationSupport（接口增强）

注解说明：Knife4j专属增强注解，用于补充@Operation的功能，实现接口排序、忽略参数、响应示例等增强效果，是开发中提升文档体验的常用注解。

核心属性：

• order（可选）：接口排序序号，数字越小，接口在文档中的排序越靠前，适合按业务逻辑排序（如查询接口在前、新增/修改/删除接口在后）。
• ignoreParameters（可选）：忽略接口中的某个/某些参数，不生成到文档中，适合无需前端传递的参数（如后端自动填充的createTime、updateTime）。
• responses（可选）：自定义接口响应示例，让前端更清晰地了解响应格式，无需查看实体类。

使用场景：添加在接口方法上，与@Operation配合使用，解决接口排序混乱、参数冗余、响应示例不清晰等问题。

完整示例：

import com.github.xiaoymin.knife4j.annotations.ApiOperationSupport;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;

@PostMapping("/add")
@Operation(
        summary = "新增课程接口",
        description = "传入课程基础信息，新增课程，自动生成课程ID，默认审核状态为未审核"
)
@ApiOperationSupport(
        order = 1, // 排序序号1，在该模块中第一个显示
        ignoreParameters = "courseId,auditStatus", // 忽略courseId（自动生成）、auditStatus（默认值），前端无需传递
        responses = {
                @io.swagger.v3.oas.annotations.responses.ApiResponse(
                        responseCode = "200",
                        description = "新增成功",
                        content = @io.swagger.v3.oas.annotations.media.Content(
                                mediaType = "application/json",
                                examples = @io.swagger.v3.oas.annotations.media.ExampleObject(
                                        value = "{\n" +
                                                "  \"code\": 200,\n" +
                                                "  \"message\": \"新增成功\",\n" +
                                                "  \"data\": {\n" +
                                                "    \"courseId\": 1001,\n" +
                                                "    \"courseName\": \"Java全栈开发\",\n" +
                                                "    \"auditStatus\": \"UNREVIEWED\"\n" +
                                                "  }\n" +
                                                "}"
                                )
                        )
                )
        }
)
public Result<CourseBase> addCourse(@RequestBody CourseAddDto dto) {
    CourseBase courseBase = courseService.add(dto);
    return Result.success(courseBase);
}

3.2.5 @Parameter（接口参数）

注解说明：用于描述单个接口参数（无论是路径参数、请求体参数、请求头参数还是查询参数），明确参数的含义、必填性、示例值等，让前端清晰知道如何传递参数。

核心属性：

• name（必填）：参数名称，与接口方法中的参数名完全一致，否则无法对应。
• description（可选）：参数详细描述，说明参数的含义、取值范围、格式等，如「课程ID，唯一标识，大于0的整数」。
• required（可选，默认false）：是否为必填参数，true表示前端必须传递，false表示可选；若为必填参数，Knife4j调试时会自动标记为必填。
• example（可选）：参数示例值，用于前端参考，如「1001」「Java全栈开发」，提升调试效率。
• in（可选，默认自动识别）：参数位置，可选值为header（请求头）、query（查询参数）、path（路径参数）、body（请求体），一般无需手动指定，Knife4j会自动识别。
• schema（可选）：参数类型，一般无需手动指定，Knife4j会自动识别参数的Java类型（如Long、String、实体类）。

使用场景：添加在接口方法的参数上，适用于所有类型的参数（路径参数、请求体参数、查询参数等），尤其适合参数较多、含义不明确的接口。

完整示例：

import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.Operation;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestParam;

@GetMapping("/get/{id}")
@Operation(summary = "根据ID查询课程详情", description = "传入课程ID，返回课程完整信息（包含课程名称、审核状态、发布状态等）")
public CourseBase getCourseById(
        // 路径参数示例（必填）
        @Parameter(
                name = "id",
                description = "课程ID，唯一标识，取值范围：大于0的整数",
                required = true,
                example = "1001",
                in = "path"
        ) @PathVariable Long id,

        // 查询参数示例（可选）
        @Parameter(
                name = "showDetail",
                description = "是否显示详情，true=显示完整信息，false=显示基础信息，默认false",
                required = false,
                example = "true",
                in = "query"
        ) @RequestParam(required = false, defaultValue = "false") Boolean showDetail
) {
    return courseService.getById(id, showDetail);
}

3.2.6 @Schema（实体类/字段）

注解说明：用于描述实体类（DTO、VO、Entity）及其字段的含义，当接口参数或返回值为实体类时，Knife4j会自动显示该实体类的字段信息，无需在每个接口中重复描述参数。

核心属性：

• description（可选）：实体类/字段的详细描述，说明实体类的用途或字段的含义。
• name（可选）：实体类/字段的别名，一般无需使用，默认使用类名/字段名。
• hidden（可选，默认false）：是否隐藏该实体类/字段，true表示不生成到文档中，适合敏感字段（如密码、手机号）。
• example（可选）：字段示例值，用于前端参考，如「UNREVIEWED」「Java全栈开发」。
• defaultValue（可选）：字段默认值，说明该字段未传递时的默认取值，如「1」「false」。
• allowableValues（可选）：字段允许的取值范围，如「UNREVIEWED,REVIEWED」，明确字段的合法取值，避免前端传递错误参数。

使用场景：添加在实体类上（描述实体类用途）和实体类的字段上（描述字段含义），适用于所有作为接口参数或返回值的实体类，是规范文档的核心注解。

完整示例：

import io.swagger.v3.oas.annotations.media.Schema;
import lombok.Data;

// 实体类注解：描述实体类用途
@Schema(description = "课程新增请求DTO，用于接收前端传递的课程新增参数")
@Data
public class CourseAddDto {

    // 字段注解：描述字段含义、示例、允许取值
    @Schema(
            description = "课程名称，长度1-50个字符，不可为空",
            example = "Java全栈开发实战",
            allowableValues = "长度1-50"
    )
    private String courseName;

    @Schema(
            description = "课程描述，长度0-500个字符，可选",
            example = "本课程涵盖Java基础、SpringBoot、微服务等核心技术，适合零基础入门"
    )
    private String courseDesc;

    @Schema(
            description = "课程分类ID，必填，对应分类表的主键",
            required = true,
            example = "201"
    )
    private Long categoryId;

    // 敏感字段：隐藏，不生成到文档中
    @Schema(description = "创建人ID，后端自动填充，前端无需传递", hidden = true)
    private Long createBy;
}

// 分页参数实体示例
@Schema(description = "通用分页请求参数，适用于所有分页查询接口")
@Data
public class PageParams {

    @Schema(
            description = "当前页码，默认值为1，取值范围：大于0的整数",
            example = "1",
            defaultValue = "1"
    )
    private Long pageNo = 1L;

    @Schema(
            description = "每页记录数，默认值为10，取值范围：1-100",
            example = "10",
            defaultValue = "10",
            allowableValues = "1-100"
    )
    private Long pageSize = 10L;
}

3.2.7 @Parameters（批量参数）

注解说明：用于批量描述多个接口参数，本质是@Parameter注解的集合，适合接口参数较多的场景，可简化代码，避免多个@Parameter注解堆叠。

核心属性：

• value（必填）：@Parameter注解的数组，批量传入多个参数的描述信息。

使用场景：接口参数较多（3个及以上）时，替代多个单独的@Parameter注解，使代码更简洁。

完整示例：

import io.swagger.v3.oas.annotations.Parameters;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.Operation;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;

@GetMapping("/search")
@Operation(summary = "课程搜索接口", description = "按多条件搜索课程，支持分页")
@Parameters({
        @Parameter(
                name = "courseName",
                description = "课程名称，模糊匹配，可选",
                example = "Java"
        ),
        @Parameter(
                name = "auditStatus",
                description = "审核状态，可选值：UNREVIEWED（未审核）、REVIEWED（已审核）",
                example = "REVIEWED"
        ),
        @Parameter(
                name = "pageNo",
                description = "当前页码，默认1",
                example = "1",
                defaultValue = "1"
        ),
        @Parameter(
                name = "pageSize",
                description = "每页记录数，默认10",
                example = "10",
                defaultValue = "10"
        )
})
public PageResult<CourseBase> searchCourse(
        @RequestParam(required = false) String courseName,
        @RequestParam(required = false) String auditStatus,
        @RequestParam(required = false, defaultValue = "1") Long pageNo,
        @RequestParam(required = false, defaultValue = "10") Long pageSize
) {
    // 业务逻辑...
    return null;
}

3.2.8 @ApiResponse（接口响应）

注解说明：用于描述接口的响应状态码、响应信息、响应格式，明确不同状态码对应的含义，帮助前端处理接口响应（如成功、失败、参数错误等）。

核心属性：

• responseCode（必填）：响应状态码，如「200」（成功）、「400」（参数错误）、「500」（服务器错误）。
• description（必填）：响应状态码的描述，如「操作成功」「参数格式错误，请检查参数」「服务器内部错误，请联系管理员」。
• content（可选）：响应体格式，可指定响应的媒体类型（如application/json）和响应示例，让前端清晰了解响应结构。

使用场景：添加在接口方法上，与@Operation配合使用，尤其适合有多种响应状态码的接口（如参数校验、权限校验、业务异常等场景）。

完整示例：

import io.swagger.v3.oas.annotations.ApiResponses;
import io.swagger.v3.oas.annotations.ApiResponse;
import io.swagger.v3.oas.annotations.Operation;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;

@PostMapping("/update")
@Operation(summary = "修改课程接口", description = "传入课程ID和修改后的信息，修改课程基础信息")
@ApiResponses({
        @ApiResponse(
                responseCode = "200",
                description = "修改成功",
                content = @io.swagger.v3.oas.annotations.media.Content(
                        mediaType = "application/json",
                        examples = @io.swagger.v3.oas.annotations.media.ExampleObject(
                                value = "{\n" +
                                        "  \"code\": 200,\n" +
                                        "  \"message\": \"修改成功\",\n" +
                                        "  \"data\": null\n" +
                                        "}"
                        )
                )
        ),
        @ApiResponse(
                responseCode = "400",
                description = "参数错误，如课程ID为空、课程名称长度不符合要求"
        ),
        @ApiResponse(
                responseCode = "404",
                description = "课程不存在，传入的课程ID无效"
        ),
        @ApiResponse(
                responseCode = "500",
                description = "服务器内部错误，请联系管理员"
        )
})
public Result updateCourse(@RequestBody CourseUpdateDto dto) {
    courseService.update(dto);
    return Result.success();
}

3.2.9 常用注解总结

为方便快速查阅，整理常用注解的核心信息，清晰区分作用对象和核心用途，可直接对照使用：

注解名称	作用对象	核心用途	是否必填
@EnableKnife4j	启动类/配置类	开启Knife4j所有功能	是
@Tag	Controller类	定义接口模块，分组展示接口	推荐
@Operation	接口方法	描述单个接口的功能、用途	推荐
@ApiOperationSupport	接口方法	接口排序、忽略参数、自定义响应示例	可选
@Parameter	接口参数	描述单个参数的含义、必填性、示例	推荐（参数多/含义不明确时）
@Parameters	接口方法	批量描述多个接口参数，简化代码	可选（参数较多时）
@Schema	实体类/字段	描述实体类用途、字段含义、示例	推荐（实体类作为参数/返回值时）
@ApiResponse	接口方法	描述接口响应状态码、响应信息	可选（多响应状态码时）

3.4 全局参数配置（Token、Header）

项目中，接口大多需要Token鉴权、统一Header（如版本号、设备类型），Knife4j支持全局参数配置，无需每次调试都手动输入，提升调试效率。

方式1：页面手动配置（临时生效）

1. 打开Knife4j文档页面，点击顶部「全局参数」按钮
2. 选择参数类型（Header/Query/Path），如Token选择Header
3. 输入参数名（如Authorization）、参数值（如Bearer xxxx），点击「添加」
4. 后续所有接口调试，都会自动携带该全局参数，无需重复输入

方式2：配置类全局配置（永久生效）

在Knife4j配置类中添加全局参数，启动服务后自动生效，适合所有环境统一配置：

@Configuration
@EnableKnife4j
public class Knife4jConfig {

    @Bean
    public OpenAPI customOpenAPI() {
        // 全局参数配置（Token）
        List<Parameter> globalParameters = new ArrayList<>();
        globalParameters.add(new Parameter()
                .name("Authorization")
                .description("Token鉴权，格式：Bearer xxxx")
                .in(ParameterIn.HEADER) // 参数位置：Header
                .required(true) // 是否必填
                .schema(new Schema().type("string"))
                .example("Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."));

        return new OpenAPI()
                .info(new Info().title("青柠代码录接口文档").version("1.0.0"))
                .components(new Components().addParameters("Authorization", new ParameterComponent()
                        .parameters(globalParameters)));
    }
}

3.5 微服务接口聚合（分布式项目）

微服务架构下，多个服务各自有独立的接口文档，开发、测试人员需要切换多个地址查看，效率低下。

Knife4j支持微服务接口聚合，将所有服务的接口文档统一聚合到一个页面，实现一站式查看、调试。

聚合核心方案（主流）

采用「Knife4j Gateway聚合模式」，基于Spring Cloud Gateway搭建网关，统一聚合所有微服务的接口文档，步骤如下（极简版）：

步骤1：网关项目导入聚合依赖

<!-- Knife4j 微服务聚合依赖 -->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-gateway-spring-boot-starter</artifactId>
    <version>3.0.3</version>
</dependency>

步骤2：网关配置聚合规则

在application.yml中配置微服务路由和接口文档聚合地址，指定每个服务的OpenAPI地址：

spring:
  cloud:
    gateway:
      routes:
        # 课程服务路由（示例）
        - id: course-service
          uri: lb://course-service
          predicates:
            - Path=/course/**
          filters:
            - name: Knife4jGatewayFilter
              args:
                swaggerDocuments: /v3/api-docs # 每个微服务的OpenAPI文档地址
        # 用户服务路由（示例）
        - id: user-service
          uri: lb://user-service
          predicates:
            - Path=/user/**
          filters:
            - name: Knife4jGatewayFilter
              args:
                swaggerDocuments: /v3/api-docs

# Knife4j 聚合配置
knife4j:
  gateway:
    enabled: true # 开启网关聚合功能
    routes:
      - name: 课程服务
        url: /course/v3/api-docs
      - name: 用户服务
        url: /user/v3/api-docs

步骤3：访问聚合文档

启动网关和所有微服务，访问网关的Knife4j文档地址：http://localhost:网关端口/doc.html，即可在左侧菜单看到所有微服务的接口分组，实现一站式查看、调试所有服务的接口。

本文由mdnice多平台发布