springdoc-openapi-maven-plugin configuration/apiDocsUrl的功能是什么？

java maven spring openapi openapi-generator

2022-09-03 07:34:10

我正在运行spredoc-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

我还在spredoc-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 连接？

答案 1

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

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

答案 2

diegomtassis和Erdinc Ay以及这个伟大的baeldung帖子都让我走上了正确的轨道。

关于springdoc-openapi-maven-plugin的事情是：它不能自己成功运行 - 仅仅将其作为唯一的依赖项添加到您的操作系统中也是不够的！pom.xml

该插件需要2个其他依赖项来做基础工作，以使其工作：

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

以下是春季MVC示例：

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

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

以下是已经存在于您的插件中的所需配置（不：您不需要此插件的版本，因为它是从您使用的继承而来的）：spring-boot-maven-pluginpom.xmlspring-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>

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

现在，如果您使用（或加快执行速度）运行Maven，您应该看到一些这样的输出：mvn verifymvn verify -DskipTests=true

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

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