当前位置：首页 > news >正文

如何区别在Spring Boot 2 和 Spring Boot 3 中使用 Knife4j：集成与配置指南

news 来源：原创 2025/4/25 3:05:38

在现代的 Web 开发中，API 文档是不可或缺的一部分。Knife4j 是基于 Swagger 的增强工具，它不仅提供了更友好的 API 文档界面，还支持更多实用的功能，如离线文档导出、全局参数配置等。本文将详细介绍如何在 Spring Boot 2 和 Spring Boot 3 中集成 Knife4j，并讲解其常用配置和注解的使用方法。

一、Knife4j 简介

Knife4j（原名 Swagger-Bootstrap-UI）是 Swagger 的增强版，提供了以下核心功能：

更友好的界面：美观、简洁的 API 文档展示。
增强功能：支持离线文档导出、全局参数、调试增强等。
兼容性：支持 Swagger 2 和 OpenAPI 3 规范。
易用性：通过简单配置即可快速集成。

二、Spring Boot 2 中使用 Knife4j

1. 依赖引入

在 pom.xml 中添加 Knife4j 的依赖：

<XML>

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <version>3.0.3</version>
</dependency>

2. 配置 Swagger

创建一个配置类，定义 Swagger 的基本信息：

<JAVA>

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.demo.controller")) // 扫描的包路径
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Knife4j Demo API")
                .description("Spring Boot 2 with Knife4j Example")
                .version("1.0")
                .build();
    }
}

3. 编写 Controller

创建一个示例 Controller，用于生成 API 文档：

<JAVA>

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/api")
@Api(tags = "示例模块")
public class DemoController {

    @GetMapping("/hello")
    @ApiOperation(value = "示例接口", notes = "返回一个简单的问候语")
    public String hello() {
        return "Hello, Knife4j!";
    }
}

4. 访问 Knife4j 文档

启动项目，访问以下 URL：

Knife4j 文档页面：http://localhost:8080/doc.html
Swagger JSON 文档：http://localhost:8080/v2/api-docs

三、Spring Boot 3 中使用 Knife4j

1. 依赖引入

Spring Boot 3 使用 Jakarta EE 9+，因此需要引入 jakarta 版本的 Knife4j 依赖：

<XML>

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
    <version>4.2.0</version>
</dependency>

2. 配置 OpenAPI

创建一个配置类，定义 OpenAPI 的基本信息：

<JAVA>

import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class Knife4jConfig {

    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
                .info(new Info()
                        .title("Knife4j Demo API")
                        .version("1.0")
                        .description("Spring Boot 3 with Knife4j Example"));
    }
}

3. 编写 Controller

创建一个示例 Controller，用于生成 API 文档：

<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.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/api")
@Tag(name = "示例模块", description = "示例模块 API")
public class DemoController {

    @GetMapping("/hello")
    @Operation(summary = "示例接口", description = "返回一个简单的问候语")
    public String hello() {
        return "Hello, Knife4j!";
    }
}

4. 访问 Knife4j 文档

启动项目，访问以下 URL：

Knife4j 文档页面：http://localhost:8080/doc.html
OpenAPI 3 JSON 文档：http://localhost:8080/v3/api-docs

四、Knife4j 常用配置

1. 配置启用 Knife4j

在 application.yml 中配置：

<YAML>

knife4j:
  enable: true # 启用 Knife4j
  setting:
    language: zh-CN # 界面语言为中文
    enable-swagger-models: true # 显示 Models
    enable-default-params: true # 启用默认参数

2. 离线文档导出

Knife4j 支持将文档导出为 Markdown、HTML 或 Word 格式：

访问 Knife4j 文档页面。
点击右上角的“离线文档”按钮。
选择导出格式并下载。

3. 全局参数

在 Swagger 配置类中添加全局参数：

<JAVA>

import springfox.documentation.service.ApiKey;
import springfox.documentation.service.SecurityScheme;

@Bean
public Docket createRestApi() {
    return new Docket(DocumentationType.SWAGGER_2)
            .securitySchemes(Collections.singletonList(new ApiKey("Authorization", "Authorization", "header")))
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.example.demo.controller"))
            .paths(PathSelectors.any())
            .build();
}

五、Knife4j 常用注解

1. 类级别注解

@Api（Swagger 2）(springboot2使用注解)：用于标识 API 模块的名称。

<JAVA>
```
@Api(tags = "示例模块")
```
@Tag（OpenAPI 3 (springboot3使用注解)）：用于标识 API 模块的名称。

<JAVA>
```
@Tag(name = "示例模块", description = "示例模块 API")
```

2. 方法级别注解

@ApiOperation（Swagger 2）(springboot2使用注解)：用于描述 API 接口的详细信息。

<JAVA>
```
@ApiOperation(value = "示例接口", notes = "返回一个简单的问候语")
```
@Operation（OpenAPI 3）(springboot3使用注解)：用于描述 API 接口的详细信息。

<JAVA>
```
@Operation(summary = "示例接口", description = "返回一个简单的问候语")
```

3. 参数级别注解

@ApiParam（Swagger 2）(springboot2使用注解)：用于描述 API 参数。

<JAVA>
```
@ApiParam(name = "name", value = "用户名称", required = true)
```
@Parameter（OpenAPI 3）(springboot3使用注解)：用于描述 API 参数。

<JAVA>
```
@Parameter(name = "name", description = "用户名称", required = true)
```