王爷追妻有点忙河北百度seo关键词排名
一、依赖作用与关系
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 关闭访问。