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

镇江集团网站建设深圳关键词推广优化

wzjs 2025/8/17 21:27:04

镇江集团网站建设,深圳关键词推广优化,做网站报价单,怎么在网站上做音乐在现代的 Web 开发中，API 文档是不可或缺的一部分。Knife4j 是基于 Swagger 的增强工具，它不仅提供了更友好的 API 文档界面，还支持更多实用的功能，如离线文档导出、全局参数配置等。本文将详细介绍如何在 Spring Boot 2 和 Sprin…

在现代的 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 {@Beanpublic 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 {@Beanpublic 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 # 启用 Knife4jsetting:language: zh-CN # 界面语言为中文enable-swagger-models: true # 显示 Modelsenable-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)
```