OpenAPI Generator 适配 Jakarta EE 的完整指南

问题描述

升级至 Spring Boot 3 后，项目移除了所有 javax.* 依赖，但 OpenAPI Generator 生成的代码仍在尝试导入 javax 相关模块（特别是 javax.annotation.Generated）。由于 Spring Boot 3 已全面迁移到 Jakarta EE 命名空间（使用 jakarta.* 包），导致项目无法编译。如何正确配置 OpenAPI Generator 使其使用 Jakarta EE 而非 javax?

解决方案

通过配置 OpenAPI Generator 的 useJakartaEe 或 useSpringBoot3 选项可解决该问题：

方案核心：启用 Jakarta EE 支持

Maven

<!-- pom.xml -->
<plugin>
  <groupId>org.openapitools</groupId>
  <artifactId>openapi-generator-maven-plugin</artifactId>
  <version>6.4.0+</version>
  <configuration>
    <configOptions>
      <useJakartaEe>true</useJakartaEe>
      <!-- 替代方案也可使用：
      <useSpringBoot3>true</useSpringBoot3> 
      -->
    </configOptions>
    <inputSpec>api.openapi.yaml</inputSpec>
    <generatorName>spring</generatorName>
  </configuration>
</plugin>

Gradle

// build.gradle
openApiGenerate {
    generatorName = "spring"
    configOptions = [
        useJakartaEe: "true"
        // 等价于： useSpringBoot3: "true"
    ]
    inputSpec = "api.openapi.yaml"
}

配置说明

1. 关键参数（二选一）：

   • useJakartaEe: true： 显式使用 Jakarta EE 命名空间
   • useSpringBoot3: true： 面向 Spring Boot 3+ 的完整支持（隐含启用 Jakarta EE）

2. 定位参数方法：

   mvn openapi-generator:help -Ddetail=true

   在输出列表中查找：

   useJakartaEe: whether to use Jakarta EE namespace (default: false)

3. 生成器更新：

   # 命令行示例
   openapi-generator generate -g spring \
     --additional-properties=useSpringBoot3=true

版本要求

必须使用 OpenAPI Generator 6.0.0 及以上版本，早期版本不支持这些选项

原理解析

选项	作用	适用场景
useJakartaEe	替换 javax → jakarta 包	通用 Jakarta EE 迁移
useSpringBoot3	同时启用 • Jakarta 包替换 • Spring Boot 3 特性适配	纯 Spring Boot 3 应用

最佳实践

1. 优先使用 useSpringBoot3：自动处理 Jakarta EE 兼容及其他 Spring Boot 3 专有配置
2. 验证生成代码：确保 @Generated 注解引入语句为：

   import jakarta.annotation.Generated; // ✅ 正确
   // 而非 javax.annotation.Generated; ❌

3. 保持生成器更新：定期升级插件以获取最新兼容性修复

常见问题排查

点击查看问题排查

1. javax 包仍未替换：

   # 查看支持的配置参数
   mvn openapi-generator:configHelp -DgeneratorName=spring

   检查控制台输出中是否存在 useJakartaEe/useSpringBoot3 选项
   → 若无，说明版本过低需升级插件

2. 新旧配置对比：

   错误配置	正确配置
   无 configOptions	包含 useJakartaEe 或 useSpringBoot3
   插件版本 < 6.0.0	版本 ≥ 6.4.0

3. 多模块项目需确保：

   <!-- 在包含API定义的模块中配置插件 -->
   <execution>
     <phase>generate-sources</phase>
     <goals>
       <goal>generate</goal>
     </goals>
   </execution>

通过以上配置，OpenAPI Generator 将自动生成兼容 Jakarta EE 的代码，无缝适配 Spring Boot 3+ 应用环境。