swagger-maven-plugin-jakarta无法生成openAPI.yaml的配置修复求助

环境与问题背景 #

• Java 17 + Spring Boot 3.3.2
• 使用swagger-maven-plugin-jakarta插件生成OpenAPI规范文件（swagger.yaml/json），原配置如下：

<plugin>
    <groupId>io.swagger.core.v3</groupId>
    <artifactId>swagger-maven-plugin-jakarta</artifactId>
    <version>2.2.22</version>
    <configuration>
        <outputDirectory>${project.build.directory}</outputDirectory>
        <outputFilename>openAPI</outputFilename>
        <outputFormats>JSON,YAML</outputFormats>
        <prettyPrint>true</prettyPrint>
        <resourcePackages>
            <resourcePackage>org.onap.so.apihandlerinfra</resourcePackage>
            <resourcePackage> org.onap.so.apihandlerinfra.tenantisolation</resourcePackage>
        </resourcePackages>
    </configuration>
    <executions>
        <execution>
            <phase>compile</phase>
            <goals>
                <goal>resolve</goal>
            </goals>
        </execution>
    </executions>
</plugin>

遇到的异常 #

1. 执行mvn clean install时报空指针错误：

[ERROR] Error resolving API specification

java.lang.NullPointerException

  at java.util.Objects.requireNonNull (Objects.java:208)
  at sun.nio.fs.WindowsFileSystem.getPath (WindowsFileSystem.java:216)
  at java.nio.file.Path.of (Path.java:147)
  at java.nio.file.Paths.get (Paths.java:69)
  at io.swagger.v3.plugin.maven.SwaggerMojo.execute (SwaggerMojo.java:114)
  ...（省略后续栈信息）

2. 将目标改为generate时，报错目标不存在：

Could not find goal 'generate' in plugin io.swagger.core.v3:swagger-maven-plugin-jakarta:2.2.22 among available goals resolve

解决方案与正确配置 #

错误原因分析 #

• 空指针异常核心原因：resourcePackages中第二个包名前存在空格，导致插件无法识别有效包路径，扫描资源时引发路径相关空指针。
• generate目标无效：该版本插件仅提供resolve一个有效目标，不存在generate目标。

修正后的插件配置 #

<plugin>
    <groupId>io.swagger.core.v3</groupId>
    <artifactId>swagger-maven-plugin-jakarta</artifactId>
    <version>2.2.22</version>
    <configuration>
        <outputDirectory>${project.build.directory}</outputDirectory>
        <outputFilename>openAPI</outputFilename>
        <outputFormats>JSON,YAML</outputFormats>
        <prettyPrint>true</prettyPrint>
        <!-- 移除包名前的空格，确保包路径有效 -->
        <resourcePackages>
            <resourcePackage>org.onap.so.apihandlerinfra</resourcePackage>
            <resourcePackage>org.onap.so.apihandlerinfra.tenantisolation</resourcePackage>
        </resourcePackages>
        <!-- 可选：设置为false避免因扫描小问题中断构建 -->
        <failOnError>false</failOnError>
        <!-- 可选：指定Spring Boot主类，帮助插件精准扫描API资源 -->
        <springBootApplication>org.onap.so.apihandlerinfra.Application</springBootApplication>
    </configuration>
    <executions>
        <execution>
            <!-- 调整为process-classes阶段，确保类已编译完成 -->
            <phase>process-classes</phase>
            <goals>
                <goal>resolve</goal>
            </goals>
        </execution>
    </executions>
</plugin>

关键调整点 #

• 清理resourcePackage中的空格：保证包名完全有效，插件能正确扫描到API注解类。
• 调整执行阶段：将compile改为process-classes，确保插件执行时项目类已编译完成，避免资源扫描失败。
• 保留有效目标：继续使用resolve目标，该版本插件无generate目标。
• 可选优化：添加springBootApplication指定主类，提升扫描精准度；开启failOnError=false降低构建中断概率。

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