What is the function of springdoc-openapi-maven-plugin configuration/apiDocsUrl?

Question

I'm running the springdoc-openapi-maven-plugin, with the following (standard) configuration:

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

The plugin appears to run, but there is no output.

I am getting a 404 error in the Maven output:

[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

I can see from my log that the 404 is on a call to: http://localhost:8080/v3/api-docs

I also see in the springdoc-openapi-maven-plugin docs the following configuration:

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

So, it appears that the plugin is attempting to open the local server during integration tests and is failing. What is the point of this? I thought that the plugin would read though my source files and generate an openapi.json file. Why does it need to make an HTTP connection to /v3/api-docs?

Answer 1

By using springdoc-openapi-ui you generate the documentation (html, json & yaml) at runtime, when your app is deployed.

In some scenarios you may want to have the documentation at build time, and that's what the springdoc-openapi-maven-plugin is for. In order for it to work you need as well to have your application started using spring-boot during the integration phase, as explained in the documentation.