使用OpenAPI Generator Maven Plugin生成客户端时遇“cannot find symbol”错误

以下是针对这个问题的具体排查和解决步骤：

• 检查API规范文件（api.json）的完整性
  确认api.json里的components/schemas节点下，有没有CreateMessageEnvelopeDTO的完整Schema定义。如果接口的请求/响应里引用了这个DTO，但没在schemas里声明，代码生成器根本不会生成这个类，自然编译报错。比如接口里写了{"$ref": "#/components/schemas/CreateMessageEnvelopeDTO"}，但schemas下没有对应节点，必须补上这个DTO的字段、类型等定义。

• 核对代码生成插件的配置
  打开pom.xml，查看你用的代码生成插件（比如openapi-generator-maven-plugin）的配置：

  • 确认generateModels参数是否设为true，modelPackage是否指定了正确的包路径；
  • 检查有没有excludeModels这类过滤配置，是不是误把CreateMessageEnvelopeDTO排除了；
  • 确保插件的版本和你的api.json规范版本兼容，比如OpenAPI 3.1的规范尽量用v6.x以上的openapi-generator插件。

• 确认生成的源码被纳入编译路径
  代码生成器通常会把类放到target/generated-sources下的子目录，比如openapi，这个目录默认可能不在Maven的编译范围内。你可以在pom.xml里添加build-helper插件来标记这个目录为源码目录：

  <plugin>
      <groupId>org.codehaus.mojo</groupId>
      <artifactId>build-helper-maven-plugin</artifactId>
      <version>3.3.0</version>
      <executions>
          <execution>
              <id>add-source</id>
              <phase>generate-sources</phase>
              <goals>
                  <goal>add-source</goal>
              </goals>
              <configuration>
                  <sources>
                      <source>${project.build.directory}/generated-sources/openapi</source>
                  </sources>
              </configuration>
          </execution>
      </executions>
  </plugin>
  

  如果用IDE开发，也可以手动右键生成目录，选择Mark Directory as -> Generated Sources Root。

• 排查生成日志的细节
  翻控制台的完整输出，除了“cannot find symbol”，看看生成阶段有没有警告或错误，比如Schema引用无效、解析失败这类提示，这些往往是DTO没生成的前置原因。如果日志里完全没提到CreateMessageEnvelopeDTO，说明生成器根本没识别到这个类的需求，得回头检查api.json里的引用是否正确。

• 检查依赖冲突
  确认项目中有没有其他依赖和生成的类包名冲突，或者插件依赖的版本导致生成逻辑异常。可以用mvn dependency:tree命令查看依赖树，排查是否有版本不兼容的情况。

内容的提问来源于stack exchange，提问作者Arthur Eirich