使用openapi-generator-maven-plugin编译报错及接口路径异常求助

一、编译报错：找不到com.example.api包/UsersApi类 #

1. 确认插件执行时机是否正确 #

openapi-generator-maven-plugin的代码生成动作必须在compile阶段前完成，否则编译时生成的代码还未生成。检查pom.xml中插件的配置，确保绑定到generate-sources阶段：

<plugin>
    <groupId>org.openapitools</groupId>
    <artifactId>openapi-generator-maven-plugin</artifactId>
    <version>你的版本号</version>
    <executions>
        <execution>
            <id>generate-jaxrs-spec</id>
            <phase>generate-sources</phase> <!-- 必须绑定此阶段 -->
            <goals>
                <goal>generate</goal>
            </goals>
            <!-- 其他配置项 -->
        </execution>
    </executions>
</plugin>

2. 确保生成目录被Maven识别为源码路径 #

Maven默认仅编译src/main/java下的代码，需手动将生成代码的目录（如target/generated-sources/openapi）加入源码路径，可通过build-helper-maven-plugin实现：

<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>

3. 验证生成代码的包路径配置 #

检查openapi-generator的configOptions，确认包名配置正确，确保生成的类落在com.example.api下：

<configuration>
    <generatorName>jaxrs-spec</generatorName>
    <inputSpec>${project.basedir}/src/main/resources/openapi.yaml</inputSpec>
    <output>${project.build.directory}/generated-sources/openapi</output>
    <configOptions>
        <packageName>com.example.api</packageName> <!-- 确认此配置无误 -->
        <!-- 其他配置项 -->
    </configOptions>
</configuration>

同时检查OpenAPI spec文件，是否通过x-java-package指定了错误包路径，覆盖了插件配置。

二、IDE未检测到报错但Maven编译失败 #

IDE（如IDEA）会自动扫描target/generated-sources目录并标记为源码根，但Maven不会自动识别。解决方法：

• 确保已添加上述build-helper-maven-plugin配置
• 刷新IDE的Maven配置（如IDEA点击Maven面板的刷新按钮），同步Maven的源码路径设置

三、接口实际路径与定义不符（仅显示/api/v1） #

1. 检查OpenAPI spec的路径定义 #

确认spec文件中接口路径是否正确：

# OpenAPI v3 示例
paths:
  /api/v1/retrieve-pwd:
    get:
      summary: 获取密码
      # 其他配置

若spec中配置了servers的url为/api/v1，则接口路径应写为/retrieve-pwd，避免路径重复：

servers:
  - url: /api/v1
paths:
  /retrieve-pwd: # 组合后为/api/v1/retrieve-pwd
    get:
      # ...

2. 检查生成器的路径相关配置 #

查看openapi-generator的configOptions，排查是否存在影响路径生成的配置：

• 若开启了<useTagsForResourceNaming>true</useTagsForResourceNaming>，可能导致标签名覆盖接口路径的部分内容
• 检查是否配置了<basePath>（OpenAPI v2），若basePath设为/api/v1，接口路径需避免重复写/api/v1

3. 查看生成的UsersApi类注解 #

直接打开target/generated-sources/openapi下的UsersApi.java，查看@Path注解内容：

@Path("/retrieve-pwd") // 正确应为该值，或结合basePath组合为/api/v1/retrieve-pwd
public interface UsersApi {
    // ...
}

如果@Path的值为/，说明spec文件路径定义有误，或生成器配置导致路径被截断。

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