使用springdoc-openapi-maven-plugin生成OpenAPI文档时连接失败

问题描述 #

配置springdoc-openapi-maven-plugin生成OpenAPI文档，同时配置了spring-boot-maven-plugin的start/stop目标，执行mvn verify时抛出连接拒绝异常：

[INFO] --- springdoc-openapi:1.4:generate (integration-test) @ my-application ---
[ERROR] An error has occured
java.net.ConnectException: Connection refused: connect
    at java.net.DualStackPlainSocketImpl.connect0 (Native Method)
    at java.net.DualStackPlainSocketImpl.socketConnect (DualStackPlainSocketImpl.java:75)
    at java.net.AbstractPlainSocketImpl.doConnect (AbstractPlainSocketImpl.java:476)
    at java.net.AbstractPlainSocketImpl.connectToAddress (AbstractPlainSocketImpl.java:218)
    at java.net.AbstractPlainSocketImpl.connect (AbstractPlainSocketImpl.java:200)
    at java.net.PlainSocketImpl.connect (PlainSocketImpl.java:162)
    at java.net.SocksSocketImpl.connect (SocksSocketImpl.java:394)
    at java.net.Socket.connect (Socket.java:606)
    at java.net.Socket.connect (Socket.java:555)
    at sun.net.NetworkClient.doConnect (NetworkClient.java:180)
    at sun.net.www.http.HttpClient.openServer (HttpClient.java:499)
    at sun.net.www.http.HttpClient.openServer (HttpClient.java:594)
    at sun.net.www.http.HttpClient.<init> (HttpClient.java:278)
    at sun.net.www.http.HttpClient.New (HttpClient.java:375)
    at sun.net.www.http.HttpClient.New (HttpClient.java:393)
    at sun.net.www.protocol.http.HttpURLConnection.getNewHttpClient (HttpURLConnection.java:1240)
    at sun.net.www.protocol.http.HttpURLConnection.plainConnect0 (HttpURLConnection.java:1167)
    at sun.net.www.protocol.http.HttpURLConnection.plainConnect (HttpURLConnection.java:1061)
    at sun.net.www.protocol.http.HttpURLConnection.connect (HttpURLConnection.java:995)
    at sun.net.www.protocol.http.HttpURLConnection.getInputStream0 (HttpURLConnection.java:1584)
    at sun.net.www.protocol.http.HttpURLConnection.getInputStream (HttpURLConnection.java:1512)
    at java.net.HttpURLConnection.getResponseCode (HttpURLConnection.java:480)
    at org.springdoc.maven.plugin.SpringDocMojo.execute (SpringDocMojo.java:110)
    at org.apache.maven.plugin.DefaultBuildPluginManager.executeMojo (DefaultBuildPluginManager.java:126)
    at org.apache.maven.lifecycle.internal.MojoExecutor.doExecute2 (MojoExecutor.java:342)
    at org.apache.maven.lifecycle.internal.MojoExecutor.doExecute (MojoExecutor.java:330)
    at org.apache.maven.lifecycle.internal.MojoExecutor.execute (MojoExecutor.java:213)
    at org.apache.maven.lifecycle.internal.MojoExecutor.execute (MojoExecutor.java:175)
    at org.apache.maven.lifecycle.internal.MojoExecutor.access$000 (MojoExecutor.java:76)
    at org.apache.maven.lifecycle.internal.MojoExecutor$1.run (MojoExecutor.java:163)
    at org.apache.maven.plugin.DefaultMojosExecutionStrategy.execute (DefaultMojosExecutionStrategy.java:39)
    at org.apache.maven.lifecycle.internal.MojoExecutor.execute (MojoExecutor.java:160)
    at org.apache.maven.lifecycle.internal.LifecycleModuleBuilder.buildProject (LifecycleModuleBuilder.java:105)
    at org.apache.maven.lifecycle.internal.LifecycleModuleBuilder.buildProject (LifecycleModuleBuilder.java:73)
    at org.apache.maven.lifecycle.internal.builder.singlethreaded.SingleThreadedBuilder.build (SingleThreadedBuilder.java:53)
    at org.apache.maven.lifecycle.internal.LifecycleStarter.execute (LifecycleStarter.java:118)
    at org.apache.maven.DefaultMaven.doExecute (DefaultMaven.java:261)
    at org.apache.maven.DefaultMaven.doExecute (DefaultMaven.java:173)
    at org.apache.maven.DefaultMaven.execute (DefaultMaven.java:101)
    at org.apache.maven.cli.MavenCli.execute (MavenCli.java:910)
    at org.apache.maven.cli.MavenCli.doMain (MavenCli.java:283)
    at org.apache.maven.cli.MavenCli.main (MavenCli.java:206)
    at sun.reflect.NativeMethodAccessorImpl.invoke0 (Native Method)
    at sun.reflect.NativeMethodAccessorImpl.invoke (NativeMethodAccessorImpl.java:62)
    at sun.reflect.DelegatingMethodAccessorImpl.invoke (DelegatingMethodAccessorImpl.java:43)
    at java.lang.reflect.Method.invoke (Method.java:498)
    at org.codehaus.plexus.classworlds.launcher.Launcher.launchEnhanced (Launcher.java:283)
    at org.codehaus.plexus.classworlds.launcher.Launcher.launch (Launcher.java:226)
    at org.codehaus.plexus.classworlds.launcher.Launcher.mainWithExitCode (Launcher.java:407)
    at org.codehaus.plexus.classworlds.launcher.Launcher.main (Launcher.java:348)
    at sun.reflect.NativeMethodAccessorImpl.invoke0 (Native Method)
    at sun.reflect.NativeMethodAccessorImpl.invoke (NativeMethodAccessorImpl.java:62)
    at sun.reflect.DelegatingMethodAccessorImpl.invoke (DelegatingMethodAccessorImpl.java:43)
    at java.lang.reflect.Method.invoke (Method.java:498)
    at org.apache.maven.wrapper.BootstrapMainStarter.start (BootstrapMainStarter.java:52)
    at org.apache.maven.wrapper.WrapperExecutor.execute (WrapperExecutor.java:161)
    at org.apache.maven.wrapper.MavenWrapperMain.main (MavenWrapperMain.java:73)

排查与解决步骤 #

• 端口一致性检查：springdoc插件默认访问http://localhost:8080/v3/api-docs，如果你的Spring Boot应用使用了非默认端口，需要在插件配置中指定正确的apiUrl，或者在spring-boot:start目标中通过jvmArguments指定端口：

  <plugin>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-maven-plugin</artifactId>
    <executions>
      <execution>
        <id>pre-integration-test</id>
        <goals>
          <goal>start</goal>
        </goals>
        <configuration>
          <jvmArguments>-Dserver.port=8081</jvmArguments>
        </configuration>
      </execution>
      <execution>
        <id>post-integration-test</id>
        <goals>
          <goal>stop</goal>
        </goals>
      </execution>
    </executions>
  </plugin>
  <plugin>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-maven-plugin</artifactId>
    <executions>
      <execution>
        <id>integration-test</id>
        <goals>
          <goal>generate</goal>
        </goals>
        <configuration>
          <apiUrl>http://localhost:8081/v3/api-docs</apiUrl>
        </configuration>
      </execution>
    </executions>
  </plugin>
  

• 确认应用启动状态：查看maven执行日志中spring-boot:start阶段的输出，确认是否有"Started [ApplicationName] in X seconds"的日志。如果没有，说明应用启动失败，检查应用的配置、依赖是否正常，手动启动应用验证能否访问/v3/api-docs端点。

• 调整插件执行顺序：确保spring-boot:start在springdoc:generate之前执行，spring-boot:stop在之后执行。正确的生命周期绑定应该是：

  • spring-boot:start → pre-integration-test阶段
  • springdoc:generate → integration-test阶段
  • spring-boot:stop → post-integration-test阶段

• 增加启动等待时间：如果应用启动较慢，spring-boot:start可以配置wait参数等待应用就绪，或者springdoc插件配置waitTimeInSeconds：

  <!-- spring-boot插件配置等待 -->
  <configuration>
    <wait>30000</wait> <!-- 30秒 -->
  </configuration>
  <!-- 或者springdoc插件配置等待 -->
  <configuration>
    <waitTimeInSeconds>30</waitTimeInSeconds>
  </configuration>
  

• 检查端口占用与防火墙：使用netstat -ano | findstr :8080（Windows）或lsof -i :8080（Linux/Mac）检查目标端口是否被其他程序占用，更换未被占用的端口重试；同时确认本地防火墙没有阻止插件访问应用端口。

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