springdoc-openapi-maven-plugin配置/apiDocsUrl的作用是什么？

Question

我正在运行 springdoc-openapi-maven-plugin，具有以下（标准）配置：

        <plugin>
            <groupId>org.springdoc</groupId>
            <artifactId>springdoc-openapi-maven-plugin</artifactId>
            <version>0.2</version>
            <executions>
                <execution>
                    <id>integration-test</id>
                    <goals>
                        <goal>generate</goal>
                    </goals>
                </execution>
            </executions>
        </plugin>

该插件似乎运行，但没有输出。

我在 Maven 输出中收到 404 错误：

[INFO] --- springdoc-openapi-maven-plugin:0.2:generate (integration-test) @ paatinc-util-websrv ---
10:40:33.930 [http-nio-8080-exec-1] INFO  o.a.c.c.C.[Tomcat].[localhost].[/] - Initializing Spring DispatcherServlet 'dispatcherServlet'
10:40:33.931 [http-nio-8080-exec-1] INFO  o.s.web.servlet.DispatcherServlet - Initializing Servlet 'dispatcherServlet'
10:40:33.956 [http-nio-8080-exec-1] INFO  o.s.web.servlet.DispatcherServlet - Completed initialization in 25 ms
10:40:33.969 [http-nio-8080-exec-1] INFO  io.paat.util.filter.LoggingFilter - GET http://localhost:8080/v3/api-docs from 127.0.0.1
[ERROR] An error has occured: Response code 404

我可以从我的日志中看到 404 正在调用：http://localhost:8080/v3/api-docs

我还在 springdoc-openapi-maven-plugin 文档中看到以下配置：

 <configuration>
  <apiDocsUrl>http://localhost:8080/v3/api-docs</apiDocsUrl>
  <outputFileName>openapi.json</outputFileName>
  <outputDir>/home/springdoc/maven-output</outputDir>
 </configuration>

因此，插件似乎在集成测试期间尝试打开本地服务器并且失败了。这有什么意义？我认为该插件会读取我的源文件并生成一个 openapi.json 文件。为什么需要与 /v3/api-docs 建立 HTTP 连接？

Answer 1

通过使用springdoc-openapi-ui，您可以在部署应用程序时在运行时生成文档（html、json 和 yaml）。

在某些情况下，您可能希望在构建时拥有文档，这就是springdoc-openapi-maven-plugin的用途。为了使其正常工作，您还需要在集成阶段让您的应用程序开始使用 spring-boot，如文档中所述。

Answer 2

diegomtassis和Erdinc Ay以及这篇很棒的 baeldung 帖子让我走上了正轨。

关于springdoc-openapi-maven-plugin 的问题是：它无法自行成功运行- 也不足以简单地将其添加为您的pom.xml!

该插件需要另外 2 个依赖项来完成基础工作才能使其正常工作：

1. 您需要将springdoc-openapi-ui插件（适用于基于 Tomcat / Spring MVC 的应用程序）或springdoc -openapi-webflux-ui插件（适用于基于 Reactive WebFlux / Netty 的应用程序）添加到您的pom.xml第一个！

这是 Spring MVC 示例：

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-ui</artifactId>
    <version>1.4.8</version>
</dependency>

2. 您需要配置spring-boot-maven-plugin以启动我们的 Spring Boot 应用程序，包括springdoc-openapi-maven-pluginopenapi.json在 Maven 集成测试阶段生成所需的API url。

spring-boot-maven-plugin这是您内部已存在的所需配置pom.xml（不：您在这里不需要此插件的版本，因为它是从您spring-boot-starter-parent使用的继承的）：

<build>
    <plugins>
        <plugin>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-maven-plugin</artifactId>
            <executions>
                <execution>
                    <id>pre-integration-test</id>
                    <goals>
                        <goal>start</goal>
                    </goals>
                </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>
            <version>1.1</version>
            <executions>
                <execution>
                    <phase>integration-test</phase>
                    <goals>
                        <goal>generate</goal>
                    </goals>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>

正如文档所述，您可以自定义诸如放置位置之类的内容，apiDocsUrl甚至可以使用 .json 文件的名称。但你不需要这样做（与皮皮所说的相反）！outputDiropenapi.jsonoutputFileName

现在，如果您使用mvn verify（或mvn verify -DskipTests=true加速执行）运行 Maven，您应该会看到如下输出：

[INFO] --- spring-boot-maven-plugin:2.3.5.RELEASE:start (pre-integration-test) @ hellobackend ---
[INFO] Attaching agents: []

  .   ____          _            __ _ _
 /\\ / ___'_ __ _ _(_)_ __  __ _ \ \ \ \
( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \
 \\/  ___)| |_)| | | | | || (_| |  ) ) ) )
  '  |____| .__|_| |_|_| |_\__, | / / / /
 =========|_|==============|___/=/_/_/_/
 :: Spring Boot ::        (v2.3.5.RELEASE)

2020-11-04 10:26:07.246  INFO 42143 --- [           main] i.j.s.SpringBootBuildpackApplication     : Starting SpringBootBuildpackApplication on PikeBook.fritz.box with PID 42143 (/Users/jonashecht/dev/spring-boot/spring-boot-kong/hellobackend/target/classes started by jonashecht in /Users/jonashecht/dev/spring-boot/spring-boot-kong/hellobackend)
2020-11-04 10:26:07.249  INFO 42143 --- [           main] i.j.s.SpringBootBuildpackApplication     : No active profile set, falling back to default profiles: default
2020-11-04 10:26:08.730  INFO 42143 --- [           main] o.s.b.web.embedded.netty.NettyWebServer  : Netty started on port(s): 8080
2020-11-04 10:26:08.742  INFO 42143 --- [           main] i.j.s.SpringBootBuildpackApplication     : Started SpringBootBuildpackApplication in 1.82 seconds (JVM running for 2.318)
[INFO]
[INFO] --- springdoc-openapi-maven-plugin:1.1:generate (default) @ hellobackend ---
2020-11-04 10:26:09.579  INFO 42143 --- [ctor-http-nio-2] o.springdoc.api.AbstractOpenApiResource  : Init duration for springdoc-openapi is: 29 ms
[INFO]
[INFO] --- spring-boot-maven-plugin:2.3.5.RELEASE:stop (post-integration-test) @ hellobackend ---
[INFO] Stopping application...
2020-11-04 10:26:09.661  INFO 42143 --- [on(2)-127.0.0.1] inMXBeanRegistrar$SpringApplicationAdmin : Application shutdown requested.
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  23.392 s
[INFO] Finished at: 2020-11-04T10:26:11+01:00
[INFO] ------------------------------------------------------------------------

openapi.json最后，您的 Spring Boot 应用程序的文件夹中应该有一个/target像这样的新文件（这就是首先使用 springdoc-openapi-maven-plugin 的目的）。如果您想查看一个完全易于理解的示例项目，可以看看这个： https: //github.com/jonashackt/spring-boot-openapi-kong/tree/main/weatherbackend