SpringDoc OpenAPI 中 @NotEmpty 注解失效问题分析与解决方案

2025-06-24 12:25:05作者：咎竹峻Karen

问题背景

在 SpringDoc OpenAPI 2.8.6 版本中，开发者发现了一个重要的功能退化问题：当在请求 DTO 上使用 @NotEmpty 注解时，生成的 OpenAPI 规范文件中不再自动包含 required 属性标记。这个问题在之前的 2.8.5 版本中工作正常，但在升级后出现了异常行为。

问题表现

开发者通常会在请求数据传输对象(DTO)中使用 @NotEmpty 注解来标记必填字段，例如：

public class ExampleRequestDto {
  @Schema(
      name = "test",
      description = "test",
      example = "test"
  )
  @NotEmpty
  private final String test;
}

按照预期，这段代码应该生成包含 required 属性的 OpenAPI YAML 文件：

required:
- test

但在 2.8.6 版本中，这个必需的标记消失了，导致 API 文档不能正确反映字段的必填要求。

问题根源

经过调查，这个问题实际上是底层依赖 swagger-core 在 2.2.29 版本中引入的一个回归性错误。该版本在处理 Jakarta Bean Validation 注解时出现了问题，特别是对于 @NotEmpty 和 @NotBlank 注解的处理逻辑存在缺陷。

解决方案

临时解决方案

降级 swagger-core 版本：开发者可以暂时将 swagger-core 降级到 2.2.28 版本，这是已知能正常工作的最后一个版本。

Maven 配置示例：

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.8.6</version>
    <exclusions>
        <exclusion>
            <groupId>io.swagger.core.v3</groupId>
            <artifactId>swagger-core-jakarta</artifactId>
        </exclusion>
    </exclusions>
</dependency>
<dependency>
    <groupId>io.swagger.core.v3</groupId>
    <artifactId>swagger-core-jakarta</artifactId>
    <version>2.2.28</version>
</dependency>

Gradle 配置示例：

dependencies {
    constraints {
        implementation("io.swagger.core.v3:swagger-core-jakarta") {
            version {
                strictly("2.2.28")
            }
        }
    }
}

显式指定 required 属性：另一种方法是直接在 @Schema 注解中明确指定 requiredMode 属性：
```
@Schema(requiredMode = Schema.RequiredMode.REQUIRED)
@NotEmpty
private final String test;
```
使用 Jakarta 注解替代：有开发者报告，使用 jakarta.validation.constraints.NotNull 替代 javax.validation.constraints.NotNull 可以解决类似问题，但这可能不适用于 @NotEmpty 和 @NotBlank 的情况。

永久解决方案

swagger-core 团队已经在 2.2.30 版本中修复了这个问题。SpringDoc OpenAPI 的最新快照版本也已经包含了这个修复。开发者可以：

等待 SpringDoc OpenAPI 发布包含修复的新版本
使用最新的 SNAPSHOT 版本进行测试

最佳实践建议

版本升级注意事项：在升级 SpringDoc OpenAPI 或相关依赖时，应该仔细检查生成的 OpenAPI 文档是否符合预期，特别是对于必填字段的标记。
注解使用一致性：考虑统一使用 Jakarta EE 的注解而非 Java EE 的注解，因为 Jakarta 是未来的发展方向。
文档验证：建议建立自动化测试来验证生成的 OpenAPI 文档是否包含所有预期的必填字段标记，这可以及早发现类似问题。
显式优于隐式：对于关键字段，即使框架支持自动推断，也建议显式使用 @Schema(requiredMode = REQUIRED) 来明确标记必填字段，这样可以减少对框架自动处理逻辑的依赖。