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

openapi + knife4j的使用

news 来源：原创 2025/9/10 10:39:40

一、依赖作用与关系

1. `springdoc-openapi-starter-webmvc-api`

• 核心功能：
基于 OpenAPI 3 规范，自动生成 API 文档元数据（JSON 格式），并集成 Spring MVC。
提供@Tag @Operation、@Schema 等注解，支持通过代码描述接口和模型。

2. `knife4j-openapi3-jakarta-spring-boot-starter`

• 核心功能：
提供增强的 Swagger UI 界面（Knife4j），支持文档搜索、离线导出、接口调试等扩展功能。
依赖 springdoc-openapi 生成元数据，仅负责界面渲染和交互优化。

• 定位：
Swagger UI 的替代品，提供更友好的文档展示和操作体验。

二、使用步骤详解

1. 添加依赖

在 pom.xml 中引入以下依赖（需注意版本兼容性）：

<!-- OpenAPI 3 元数据生成 -->
<dependency><groupId>org.springdoc</groupId><artifactId>springdoc-openapi-starter-webmvc-api</artifactId><version>2.3.0</version>
</dependency><!-- Knife4j 增强 UI -->
<dependency><groupId>com.github.xingfudeshi</groupId><artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId><version>4.5.0</version>
</dependency>

版本说明

• springdoc-openapi ≥ 2.0：支持 Spring Boot 3.x（Jakarta EE 9+）
• knife4j-openapi3-jakarta ≥ 4.0：适配 Jakarta 命名空间

2. 基础配置

在 application.yml 中添加必要配置：

springdoc:swagger-ui:path: /swagger-ui  # 原生 UI 路径（可选）api-docs:path: /v3/api-docs      # OpenAPI JSON 元数据路径default-consumes-media-type: application/jsondefault-produces-media-type: application/json# Knife4j 配置（可选）
knife4j:enable: truesetting:language: zh-CN         # 中文界面enable-footer: false    # 禁用页脚广告

3. 配置类（可选）

自定义全局 OpenAPI 元数据（如标题、版本）：

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 OpenApiConfig {@Beanpublic OpenAPI customOpenAPI() {return new OpenAPI().info(new Info().title("电商系统 API 文档").version("1.0").description("管理后台接口文档"));}
}

4. 接口代码注解

使用注解描述接口和模型：

4.1 接口描述（Controller）

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.tags.Tag;@RestController
@RequestMapping("/brand")
@Tag(name = "品牌管理", description = "商品品牌相关接口")
public class BrandController {@PostMapping("/create")@Operation(summary = "创建品牌", description = "需要管理员权限")public Result<Long> createBrand(@RequestBody @Valid BrandCreateReqVO reqVO,@Parameter(description = "操作人 ID", required = true) @RequestHeader("X-User-Id") Long userId) {// 业务逻辑}
}

4.2 模型描述（DTO/VO）

import io.swagger.v3.oas.annotations.media.Schema;@Data
@Schema(name = "BrandCreateReqVO", description = "品牌创建请求体")
public class BrandCreateReqVO {@Schema(description = "品牌名称", example = "Apple", requiredMode = REQUIRED)@NotBlank(message = "名称不能为空")private String name;@Schema(description = "排序值", example = "1", minimum = "0")@Min(value = 0, message = "排序值最小为0")private Integer sort;
}

5. 访问文档界面

启动项目后访问以下 URL：

功能	URL
Knife4j 增强 UI	`http://localhost:8080/doc.html`
原生 Swagger UI	`http://localhost:8080/swagger-ui`
OpenAPI 元数据	`http://localhost:8080/v3/api-docs`

三、Knife4j 特色功能

1. 文档增强特性

• 离线导出：支持 Markdown/HTML/Word 格式导出
• 接口搜索：全局关键字搜索 API
• 调试增强：表单参数自动生成、响应结果格式化

安全控制（生产建议）

knife4j:basic:enable: trueusername: adminpassword: 123456

四、常见问题

1. 依赖冲突

• 现象：与旧版 Springfox 库（如 springfox-swagger2）冲突
• 解决：移除所有 springfox 相关依赖

2. 注解不生效

• 检查项：

确保 @EnableWebMvc 未覆盖默认配置
验证 @Schema 是否标注在 Getter 方法或字段上

3. 是否需要同时引入两个依赖？

• 必须：springdoc-openapi 生成元数据，knife4j 负责渲染 UI
• 若仅需原生 UI：可只依赖 springdoc-openapi-ui

五、总结

通过 springdoc-openapi + knife4j 的组合，开发者可以：

标准化：遵循 OpenAPI 3 规范生成文档
高效协作：提供清晰的接口定义和调试工具
美观易用：Knife4j 的增强 UI 提升使用体验

建议在开发阶段启用文档，生产环境通过 knife4j.enable=false 关闭访问。