openapi + knife4j的使用

一、依赖作用与关系

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/json
  default-produces-media-type: application/json

# Knife4j 配置（可选）
knife4j:
  enable: true
  setting:
    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 {

    @Bean
    public 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: true
    username: admin
    password: 123456

---

四、常见问题

1. 依赖冲突

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

2. 注解不生效

• 检查项：

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

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

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

---

五、总结

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

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

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