springdoc / springdoc-openapi-maven-plugin Goto Github PK

Library for OpenAPI 3 with spring-boot

License: Apache License 2.0

Java 100.00%

springdoc-openapi-maven-plugin's Introduction

IMPORTANT: springdoc-openapi v1.8.0 is the latest Open Source release supporting Spring Boot 2.x and 1.x.

An extended support for springdoc-openapi v1 project is now available for organizations that need support beyond 2023.

For more details, feel free to reach out: [email protected]

springdoc-openapi is on Open Collective. If you ❤️ this project consider becoming a sponsor.

This project is sponsored by

Full documentation
Introduction
Getting Started
Acknowledgements
- Contributors
- Additional Support

Full documentation

Introduction

The springdoc-openapi Java library helps automating the generation of API documentation using Spring Boot projects. springdoc-openapi works by examining an application at runtime to infer API semantics based on Spring configurations, class structure and various annotations.

The library automatically generates documentation in JSON/YAML and HTML formatted pages. The generated documentation can be complemented using swagger-api annotations.

This library supports:

OpenAPI 3
Spring-boot v3 (Java 17 & Jakarta EE 9)
JSR-303, specifically for @NotNull, @Min, @Max, and @Size.
Swagger-ui
OAuth 2
GraalVM native images

The following video introduces the Library:

https://youtu.be/utRxyPfFlDw

For spring-boot v3 support, make sure you use springdoc-openapi v2

This is a community-based project, not maintained by the Spring Framework Contributors (Pivotal)

Getting Started

Library for springdoc-openapi integration with spring-boot and swagger-ui

Automatically deploys swagger-ui to a Spring Boot 3.x application
Documentation will be available in HTML format, using the official swagger-ui jars.
The Swagger UI page should then be available at http://server: port/context-path/swagger-ui.html and the OpenAPI description will be available at the following url for json format: http://server:port/context-path/v3/api-docs
- server: The server name or IP
- port: The server port
- context-path: The context path of the application
Documentation can be available in yaml format as well, on the following path: /v3/api-docs.yaml
Add the springdoc-openapi-ui library to the list of your project dependencies (No additional configuration is needed):

   <dependency>
      <groupId>org.springdoc</groupId>
      <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
      <version>last-release-version</version>
   </dependency>

This step is optional: For custom path of the swagger documentation in HTML format, add a custom springdoc property, in your spring-boot configuration file:

# swagger-ui custom path
springdoc.swagger-ui.path=/swagger-ui.html

Spring-boot with OpenAPI Demo applications.

Source Code for Demo Applications.

Demo Spring Boot 3 Web MVC with OpenAPI 3.

Demo Spring Boot 3 WebFlux with OpenAPI 3.

Demo Spring Boot 3 WebFlux with Functional endpoints OpenAPI 3.

Demo Spring Boot 3 and Spring Cloud Function Web MVC.

Demo Spring Boot 3 and Spring Cloud Function WebFlux.

Demo Spring Boot 3 and Spring Cloud Gateway.

Integration of the library in a Spring Boot 3.x project without the swagger-ui:

Documentation will be available at the following url for json format: http://server: port/context-path/v3/api-docs
- server: The server name or IP
- port: The server port
- context-path: The context path of the application
Documentation will be available in yaml format as well, on the following path : /v3/api-docs.yaml
Add the library to the list of your project dependencies. (No additional configuration is needed)

   <dependency>
      <groupId>org.springdoc</groupId>
      <artifactId>springdoc-openapi-starter-webmvc-api</artifactId>
      <version>last-release-version</version>
   </dependency>

This step is optional: For custom path of the OpenAPI documentation in Json format, add a custom springdoc property, in your spring-boot configuration file:

# /api-docs endpoint custom path
springdoc.api-docs.path=/api-docs

This step is optional: If you want to disable springdoc-openapi endpoints, add a custom springdoc property, in your spring-boot configuration file:

# disable api-docs
springdoc.api-docs.enabled=false

Error Handling for REST using @ControllerAdvice

To generate documentation automatically, make sure all the methods declare the HTTP Code responses using the annotation: @ResponseStatus.

Adding API Information and Security documentation

The library uses spring-boot application auto-configured packages to scan for the following annotations in spring beans: OpenAPIDefinition and Info. These annotations declare, API Information: Title, version, licence, security, servers, tags, security and externalDocs. For better performance of documentation generation, declare @OpenAPIDefinition and @SecurityScheme annotations within a Spring managed bean.

spring-webflux support with Annotated Controllers

Documentation can be available in yaml format as well, on the following path : /v3/api-docs.yaml
Add the library to the list of your project dependencies (No additional configuration is needed)

   <dependency>
      <groupId>org.springdoc</groupId>
      <artifactId>springdoc-openapi-starter-webflux-ui</artifactId>
      <version>last-release-version</version>
   </dependency>

This step is optional: For custom path of the swagger documentation in HTML format, add a custom springdoc property, in your spring-boot configuration file:

# swagger-ui custom path
springdoc.swagger-ui.path=/swagger-ui.html

The springdoc-openapi libraries are hosted on maven central repository. The artifacts can be viewed accessed at the following locations:

Releases:

https://s01.oss.sonatype.org/content/groups/public/org/springdoc/ .

Snapshots:

https://s01.oss.sonatype.org/content/repositories/snapshots/org/springdoc/ .

Acknowledgements

Contributors

springdoc-openapi is relevant and updated regularly due to the valuable contributions from its contributors.

Thanks you all for your support!

Additional Support

Spring Team - Thanks for their support by sharing all relevant resources around Spring projects.
JetBrains - Thanks a lot for supporting springdoc-openapi project.

springdoc-openapi-maven-plugin's People

Contributors

Stargazers

Watchers

springdoc-openapi-maven-plugin's Issues

missing required property version

Hi,
I have following configuraiton:

<plugin> <groupId>org.springdoc</groupId> <artifactId>springdoc-openapi-maven-plugin</artifactId> <version>1.0</version> <executions> <execution> <id>integration-test</id> <goals> <goal>generate</goal> </goals> </execution> </executions> <configuration> <apiDocsUrl>http://localhost:8080/v3/api-docs</apiDocsUrl> <outputFileName>openapi.json</outputFileName> <outputDir>${project.build.directory}</outputDir> </configuration> </plugin>
then following json is generated:
"openapi": "3.0.1", "info": { "title": "License plate 'reactive version' ", "description": "" }, .....

In intellij idea and also openapi-generator-maven-plugin, I'm getting error that required property version is missing.

I need to manually change it to:
"info": { "title": "License plate 'reactive version' ", "description": "", "version": "0.1" },
Do I miss something?
Thank you.

403 response code while generating OAS spec

Hi Guys,

When I run mvn verify on my SpringBoots service in localhost I get the following error:

[ERROR] An error has occured: Response code 403

I'm using the standard configuration and the service runs fine. Here are further details:

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

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

2021-03-30 09:35:30.415 INFO 11293 --- [ main] c.d.s.SubscriptionsApiApplication : Starting SubscriptionsApiApplication using Java 11.0.7 on AMAC02XH0T6JHD4 with PID 11293 (/Users/j.f.de.brito.serrao/Development/vodafone/subscriptions-api/target/classes started by j.f.de.brito.serrao in /Users/j.f.de.brito.serrao/Development/vodafone/subscriptions-api)
2021-03-30 09:35:30.417 INFO 11293 --- [ main] c.d.s.SubscriptionsApiApplication : No active profile set, falling back to default profiles: default
2021-03-30 09:35:31.556 INFO 11293 --- [ main] o.s.b.w.embedded.tomcat.TomcatWebServer : Tomcat initialized with port(s): 8080 (http)
2021-03-30 09:35:31.565 INFO 11293 --- [ main] o.apache.catalina.core.StandardService : Starting service [Tomcat]
2021-03-30 09:35:31.565 INFO 11293 --- [ main] org.apache.catalina.core.StandardEngine : Starting Servlet engine: [Apache Tomcat/9.0.44]
2021-03-30 09:35:31.654 INFO 11293 --- [ main] o.a.c.c.C.[Tomcat].[localhost].[/] : Initializing Spring embedded WebApplicationContext
2021-03-30 09:35:31.655 INFO 11293 --- [ main] w.s.c.ServletWebServerApplicationContext : Root WebApplicationContext: initialization completed in 1191 ms
2021-03-30 09:35:31.917 INFO 11293 --- [ main] o.s.s.concurrent.ThreadPoolTaskExecutor : Initializing ExecutorService 'applicationTaskExecutor'
2021-03-30 09:35:32.475 INFO 11293 --- [ main] o.s.b.a.e.web.EndpointLinksResolver : Exposing 2 endpoint(s) beneath base path '/actuator'
2021-03-30 09:35:32.516 INFO 11293 --- [ main] o.s.b.w.embedded.tomcat.TomcatWebServer : Tomcat started on port(s): 8080 (http) with context path ''
2021-03-30 09:35:32.532 INFO 11293 --- [ main] c.d.s.SubscriptionsApiApplication : Started SubscriptionsApiApplication in 2.477 seconds (JVM running for 3.116)
[INFO]
[INFO] --- springdoc-openapi-maven-plugin:1.3:generate (integration-test) @ subscriptions-api ---
[ERROR] An error has occured: Response code 403
[INFO]
[INFO] --- spring-boot-maven-plugin:2.3.4.RELEASE:stop (post-integration-test) @ subscriptions-api ---
[INFO] Stopping application...
2021-03-30 09:35:34.016 INFO 11293 --- [on(2)-127.0.0.1] inMXBeanRegistrar$SpringApplicationAdmin : Application shutdown requested.
2021-03-30 09:35:34.050 INFO 11293 --- [on(2)-127.0.0.1] o.s.s.concurrent.ThreadPoolTaskExecutor : Shutting down ExecutorService 'applicationTaskExecutor'
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 14.560 s
[INFO] Finished at: 2021-03-30T09:35:34+01:00

org.springframework.boot spring-boot-maven-plugin 2.3.4.RELEASE -Dspring.application.admin.enabled=true pre-integration-test start post-integration-test stop org.springdoc springdoc-openapi-maven-plugin 1.3 integration-test generate

Plugin not failing build on connection error

When I added this plugin to my pom I forgot to configure the url so that it would know about the random port the service is starting up on. I expect that this would've caused the build to fail, but I only noticed because I manually looked for the open api file and noticed it was missing.

It would be nice if the plugin would cause the build to fail on connection errors because we are planning on using the output file in our pipeline.

This is a snippet of my log:

19:16:12.353 [main] INFO  [] o.s.b.w.e.netty.NettyWebServer  - Netty started on port[s]: 54826
19:16:22.448 [main] INFO  [] c.n.c.t.api.impl.MainApplication  - Started MainApplication in 30.57 seconds [JVM running for 35.115]
[INFO]
[INFO] --- springdoc-openapi-maven-plugin:1.1:generate (integration-test) @ tokenization-api-impl ---
[ERROR] An error has occured: Response code 403
[INFO]
[INFO] --- spring-boot-maven-plugin:2.3.2.RELEASE:stop (post-integration-test) @ tokenization-api-impl ---
[INFO] Stopping application...
19:16:24.128 [RMI TCP Connection(2)-127.0.0.1] INFO  [] o.s.b.a.SpringApplicationAdminMXBeanRegistrar$SpringApplicationAdmin  - Application shutdown requested.

The plugin version is 1.1

There is no way to generate multiple open api files in one plugin config

Plugin configuration is global for the whole plugin. There is no way to do something like below:

	<groupId>org.springdoc</groupId>
	<artifactId>springdoc-openapi-maven-plugin</artifactId>
	<version>1.4</version>
	<executions>
		<execution>
			<id>admin-api-generation</id>
			<phase>integration-test</phase>
			<goals>
				<goal>generate</goal>
			</goals>
			<configuration>
				<apiDocsUrl>http://localhost:8080/v3/api-docs/admin</apiDocsUrl>
				<outputFileName>openapi-admin.json</outputFileName>
				<outputDir>${project.build.directory}</outputDir>
			</configuration>
		</execution>
		<execution>
			<id>user-api-generation</id>
			<phase>integration-test</phase>
			<goals>
				<goal>generate</goal>
			</goals>
			<configuration>
				<apiDocsUrl>http://localhost:8080/v3/api-docs/user</apiDocsUrl>
				<outputFileName>openapi-user.json</outputFileName>
				<outputDir>${project.build.directory}</outputDir>
			</configuration>
		</execution>
	</executions>
</plugin>`

Zombie process

When executing the verify maven phase and generating the openapi.json file, maven finishes with success, however the java process associated with it running on port 9001 is not exited and you have to kill it every time you want to run verify phase again.

Dependencies used:

springdoc-openapi-ui 1.5.9
springdoc-openapi-maven-plugin 1.3

Will the plugin generate multiple files if GroupedOpenAPI is used?

It does not look like it in the source code: here or here

And if so, how are the filenames generated? openapi-.<json|yaml>

Created Openapi.json file changes each time

Every time I have a new controller or api and want to run the mvn to add it to openapi.json file, the new file has some changes in object orders. It makes it really difficult in terms of code review in pull request b/c basically lots of line is just been moved to a new place. Is there anyway to skip this ordering changes?

[Question] Error: Spring application did not start before the configured timeout

Trying to use the plugin for integration tests like documented, but I always get 'Spring application did not start before the configured timeout'. However, spring server app is saying:

18:30:14.442 [http-nio-8080-exec-1] INFO  o.s.web.servlet.DispatcherServlet.initServletBean - Initializing Servlet 'dispatcherServlet'
18:30:14.446 [http-nio-8080-exec-1] INFO  o.s.web.servlet.DispatcherServlet.initServletBean - Completed initialization in 4 ms
18:30:21.918 [http-nio-8080-exec-2] WARN  o.s.w.s.m.s.DefaultHandlerExceptionResolver.logException - Resolved [org.springframework.web.HttpRequestMethodNotSupportedException: Request method 'GET' not supported]
18:31:05.899 [http-nio-8080-exec-3] WARN  o.s.w.s.m.s.DefaultHandlerExceptionResolver.logException - Resolved [org.springframework.web.HttpRequestMethodNotSupportedException: Request method 'GET' not supported]

Because of this, I guess that the plugin simply has not found out that the app already has started.

This is my question:
How does the plugin try to find out if the application has started? JMX/RMI? Which port? Which MBean?

Generate api document by Maven plugin during compilation

Currently, springdoc must be running the program before accessing the API documentation interface.
But sometimes the request definition is modified and the program is not launched At this point, through the Maven plugin, documents can be generated during compilation and quickly delivered to testing people.

So, I would like to ask, can this feature be implemented in the future?

setBasePath in generated ApiClient sets OAuth2 path as well

My apologies if this is in the wrong place; it's not immediately clear where the code generator resides.

When Maven generates client code, including the ApiClient class, there is the following method:

  /**
   * Sets the base URL to the location where the OpenAPI document is being served.
   *
   * @param basePath The base URL to the target host.
   * @return a {@link org.openapitools.client.ApiClient} object.
   */
  public ApiClient setBasePath(String basePath) {
    this.basePath = basePath;
    setOauthBasePath(basePath);
    return this;
  }

What isn't clear is why setOauthBasePath(basePath) is invoked. The OAuth2 server resides on a different endpoint from the REST service. The REST service doesn't expose an authentication/authorisation endpoint either.

Is this a bug, or is it expected behaviour?

Add "failOnError" option

When the plugin fails to retrieve the openapi file fromt the server, it should error stop the maven build process.
Currently an error is emitted but the maven process continues.

e.g. [ERROR] An error has occured: Response code 401

springdoc-openapi-maven-plugin:generate fails if the target directory doesn't exist

I have a module in a multi-module project that is just for generating the OpenAPI file by adding the necessary dependencies. Since there's no code in this module, I have disabled maven-jar-plugin. The openapi generate goal fails since the target directory is not created.

[INFO] --- springdoc-openapi-maven-plugin:0.2:generate (integration-test) @ obfuscated-integration ---
[ERROR] An error has occured
java.nio.file.NoSuchFileException: /home/user/git/obfuscated/submodule/target/openapi.json
    at sun.nio.fs.UnixException.translateToIOException (UnixException.java:92)
    at sun.nio.fs.UnixException.rethrowAsIOException (UnixException.java:111)
    at sun.nio.fs.UnixException.rethrowAsIOException (UnixException.java:116)
    at sun.nio.fs.UnixFileSystemProvider.newByteChannel (UnixFileSystemProvider.java:219)
    at java.nio.file.spi.FileSystemProvider.newOutputStream (FileSystemProvider.java:478)
    at java.nio.file.Files.newOutputStream (Files.java:223)
    at java.nio.file.Files.write (Files.java:3488)
    at org.springdoc.maven.plugin.SpringDocMojo.execute (SpringDocMojo.java:47)
    at org.apache.maven.plugin.DefaultBuildPluginManager.executeMojo (DefaultBuildPluginManager.java:137)
    at org.apache.maven.lifecycle.internal.MojoExecutor.execute (MojoExecutor.java:210)
    at org.apache.maven.lifecycle.internal.MojoExecutor.execute (MojoExecutor.java:156)
    at org.apache.maven.lifecycle.internal.MojoExecutor.execute (MojoExecutor.java:148)
    at org.apache.maven.lifecycle.internal.LifecycleModuleBuilder.buildProject (LifecycleModuleBuilder.java:117)
    at org.apache.maven.lifecycle.internal.LifecycleModuleBuilder.buildProject (LifecycleModuleBuilder.java:81)
    at org.apache.maven.lifecycle.internal.builder.singlethreaded.SingleThreadedBuilder.build (SingleThreadedBuilder.java:56)
    at org.apache.maven.lifecycle.internal.LifecycleStarter.execute (LifecycleStarter.java:128)
    at org.apache.maven.DefaultMaven.doExecute (DefaultMaven.java:305)
    at org.apache.maven.DefaultMaven.doExecute (DefaultMaven.java:192)
    at org.apache.maven.DefaultMaven.execute (DefaultMaven.java:105)
    at org.apache.maven.cli.MavenCli.execute (MavenCli.java:956)
    at org.apache.maven.cli.MavenCli.doMain (MavenCli.java:288)
    at org.apache.maven.cli.MavenCli.main (MavenCli.java:192)
    at jdk.internal.reflect.NativeMethodAccessorImpl.invoke0 (Native Method)
    at jdk.internal.reflect.NativeMethodAccessorImpl.invoke (NativeMethodAccessorImpl.java:62)
    at jdk.internal.reflect.DelegatingMethodAccessorImpl.invoke (DelegatingMethodAccessorImpl.java:43)
    at java.lang.reflect.Method.invoke (Method.java:567)
    at org.codehaus.plexus.classworlds.launcher.Launcher.launchEnhanced (Launcher.java:289)
    at org.codehaus.plexus.classworlds.launcher.Launcher.launch (Launcher.java:229)
    at org.codehaus.plexus.classworlds.launcher.Launcher.mainWithExitCode (Launcher.java:415)
    at org.codehaus.plexus.classworlds.launcher.Launcher.main (Launcher.java:356)

Plugin does not generate responses correctly

Hi,
Here is a sample code:

_@ApiResponse(responseCode = "400", description = RC_400,

content = @content(mediaType = MediaType.APPLICATION_JSON_VALUE,

schema = @Schema (type = "string", maxLength = 200, minLength = 10, pattern = "[a-zA-Z]",

implementation = Error.class))),_

from this the generator generates:

_"400":

description: Bad Request
content:

application/json:

schema:

type: string_

But he would have to generate that instead:

_"400":

description: Bad Request
content:

application/json:

schema:

maxLength: 200
minLength: 10
pattern: "[a-zA-Z]"
type: string_

Is there any way to fix this problem?

Multiple Output directories

Hi @bnasslahsen, I would like to create a PR for this repo in which I will be including the availability to generate the openapi.json to one, two, or more output directories.

Please could you point me to the guidelines for contributing to this project?

Thanks

html output

Generate html instead of or + json

UI and generated json display -> integer($int64) instead of long

Hello,

Just a small thing I wanted to report.
On a java primitive long, such as:

@Schema(description = "why integer($int64)?") private long someLongPrimitive;

The plugin is generating

"someLongPrimitive": { "type": "integer", "description": "why integer($int64)?", "format": "int64" },

And the UI, following the json displays

someLongPrimitive* | integer($int64)

Is it possible to call a primitive long, long?
Hope not to trouble.
Thank you

Add -Dspringdoc.writer-with-default-pretty-printer as maven plugin configuration parameter

Use case:
We generate open-api documentation as part of the development process, and then commit the documentation to the repository. Developers use mvn verify, but sometimes they forget about this cumbersome system parameter, and commit one-line generated open-api document to git. It would be much more convenient and practical to have this parameter as maven plugin configuration parameter.

Auto JSON format openapi.json

Hey team,

While using this plugin, I thought it might be cool to have JSON auto-formatting.

When generating the openapi.json file it creates a big one-liner. I know that people don't sit around and read the schema generated, but it comes in handy when you want to test quickly if your schema is generated the way you want it to be.

This might impact in a way that new dependencies are added to not write the whole formatted, what are your thoughts? :)

Error while working with context-path

After adding a single line:
server.servlet.context-path=/mytest

I start receiving an error on (mvn clean verify)

[INFO] 
[INFO] --- springdoc-openapi-maven-plugin:1.4:generate (integration-test) @ demo ---
[ERROR] An error has occured: Response code 404
[INFO] 
[INFO] --- spring-boot-maven-plugin:3.1.0:stop (default) @ demo ---

See here. Just clone to reproduce

https://github.com/guilhermecgs/demo/commit/1865f486a53316bac0938a863c2c27573b1d1249

Setting all imports with full path

Is it possible to set import statements with full path instead of wildcard pattern ?

instead of

import java.util.*

use
import java.util.Map
import java.util.List
...

Springdoc-openapi-maven-plugin without springboot

hello,

is there any simple way how to integrate springdoc-openapi-maven-plugin for the Spring WebMvc framework.

Currently I see we need to run application in integration tests via spring-boot-maven-plugin, but I don't see any example to run it only with Spring WebMvc.

Do you have any guide for this?

Thanks for your help,
Milos

[Feature request] output in YAML/YML format, and preferably pretty printed (even for the current JSON one)

Hello,

First of all, a big thanks for this project.
This is a feature request, an idea to possibly make this project even more interesting, hope not to trouble.

Currently, this plugin is doing a great job in generating the JSON output.

First questions, can the output be pretty printed instead of the one liner?

Second question, would it be possible to add an option to have the output as (pretty printed) YAML/YML as well?

Thank you for your help.

java.net.ConnectException: Connection refused (Connection refused)

Output log for mvn clean verify -Dspring.application.admin.enabled=true below

Application was started

INFO [is,,,] 7851 --- [           main] o.e.jetty.server.AbstractConnector       : Started ServerConnector@3dc82e6a{HTTP/1.1,[http/1.1]}{0.0.0.0:10000}
INFO [is,,,] 7851 --- [           main] o.s.b.web.embedded.jetty.JettyWebServer  : Jetty started on port(s) 10000 (http/1.1) with context path '/'
INFO [is,,,] 7851 --- [           main] com.cdek.is.IsApplication                : Started IsApplication in 10.874 seconds (JVM running for 12.087)

springdoc-openapi-maven-plugin:0.3:generate

INFO] --- springdoc-openapi-maven-plugin:0.3:generate (integration-test) @ is ---
[ERROR] An error has occured
java.net.ConnectException: Connection refused (Connection refused)
    at java.net.PlainSocketImpl.socketConnect (Native Method)
    at java.net.AbstractPlainSocketImpl.doConnect (AbstractPlainSocketImpl.java:350)
    at java.net.AbstractPlainSocketImpl.connectToAddress (AbstractPlainSocketImpl.java:206)
    at java.net.AbstractPlainSocketImpl.connect (AbstractPlainSocketImpl.java:188)
    at java.net.SocksSocketImpl.connect (SocksSocketImpl.java:392)
    at java.net.Socket.connect (Socket.java:589)
    at java.net.Socket.connect (Socket.java:538)
    at sun.net.NetworkClient.doConnect (NetworkClient.java:180)
    at sun.net.www.http.HttpClient.openServer (HttpClient.java:463)
    at sun.net.www.http.HttpClient.openServer (HttpClient.java:558)
    at sun.net.www.http.HttpClient.<init> (HttpClient.java:242)
    at sun.net.www.http.HttpClient.New (HttpClient.java:339)
    at sun.net.www.http.HttpClient.New (HttpClient.java:357)
    at sun.net.www.protocol.http.HttpURLConnection.getNewHttpClient (HttpURLConnection.java:1220)
    at sun.net.www.protocol.http.HttpURLConnection.plainConnect0 (HttpURLConnection.java:1156)
    at sun.net.www.protocol.http.HttpURLConnection.plainConnect (HttpURLConnection.java:1050)
    at sun.net.www.protocol.http.HttpURLConnection.connect (HttpURLConnection.java:984)
    at sun.net.www.protocol.http.HttpURLConnection.getInputStream0 (HttpURLConnection.java:1564)
    at sun.net.www.protocol.http.HttpURLConnection.getInputStream (HttpURLConnection.java:1492)
    at java.net.HttpURLConnection.getResponseCode (HttpURLConnection.java:480)
    at org.springdoc.maven.plugin.SpringDocMojo.execute (SpringDocMojo.java:43)
    at org.apache.maven.plugin.DefaultBuildPluginManager.executeMojo (DefaultBuildPluginManager.java:137)
    at org.apache.maven.lifecycle.internal.MojoExecutor.execute (MojoExecutor.java:210)
    at org.apache.maven.lifecycle.internal.MojoExecutor.execute (MojoExecutor.java:156)
    at org.apache.maven.lifecycle.internal.MojoExecutor.execute (MojoExecutor.java:148)
    at org.apache.maven.lifecycle.internal.LifecycleModuleBuilder.buildProject (LifecycleModuleBuilder.java:117)
    at org.apache.maven.lifecycle.internal.LifecycleModuleBuilder.buildProject (LifecycleModuleBuilder.java:81)
    at org.apache.maven.lifecycle.internal.builder.singlethreaded.SingleThreadedBuilder.build (SingleThreadedBuilder.java:56)
    at org.apache.maven.lifecycle.internal.LifecycleStarter.execute (LifecycleStarter.java:128)
    at org.apache.maven.DefaultMaven.doExecute (DefaultMaven.java:305)
    at org.apache.maven.DefaultMaven.doExecute (DefaultMaven.java:192)
    at org.apache.maven.DefaultMaven.execute (DefaultMaven.java:105)
    at org.apache.maven.cli.MavenCli.execute (MavenCli.java:956)
    at org.apache.maven.cli.MavenCli.doMain (MavenCli.java:288)
    at org.apache.maven.cli.MavenCli.main (MavenCli.java:192)
    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:282)
    at org.codehaus.plexus.classworlds.launcher.Launcher.launch (Launcher.java:225)
    at org.codehaus.plexus.classworlds.launcher.Launcher.mainWithExitCode (Launcher.java:406)
    at org.codehaus.plexus.classworlds.launcher.Launcher.main (Launcher.java:347)
    at org.codehaus.classworlds.Launcher.main (Launcher.java:47)

pom.xml

<plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
                <configuration>
                    <wait>1000</wait>
                    <maxAttempts>180</maxAttempts>
                    <jvmArguments>
                        -Dspring.application.admin.enabled=true
                    </jvmArguments>
                </configuration>
                <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>0.3</version>
                <executions>
                    <execution>
                        <id>integration-test</id>
                        <goals>
                            <goal>generate</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>

Fails to generate openapi.json spec

I tried running ./mvnw springdoc-openapi:generate and also ./mvn verify but i get a weird ConnectException somehow:

[ERROR] An error has occured
java.net.ConnectException: Connection refused: connect
    at sun.nio.ch.Net.connect0 (Native Method)
    at sun.nio.ch.Net.connect (Net.java:579)
    at sun.nio.ch.Net.connect (Net.java:568)
    at sun.nio.ch.NioSocketImpl.connect (NioSocketImpl.java:588)
    at java.net.Socket.connect (Socket.java:633)
    at java.net.Socket.connect (Socket.java:583)
    at sun.net.NetworkClient.doConnect (NetworkClient.java:183)
    at sun.net.www.http.HttpClient.openServer (HttpClient.java:498)
    at sun.net.www.http.HttpClient.openServer (HttpClient.java:603)
    at sun.net.www.http.HttpClient.<init> (HttpClient.java:246)
    at sun.net.www.http.HttpClient.New (HttpClient.java:351)
    at sun.net.www.http.HttpClient.New (HttpClient.java:373)
    at sun.net.www.protocol.http.HttpURLConnection.getNewHttpClient (HttpURLConnection.java:1309)
    at sun.net.www.protocol.http.HttpURLConnection.plainConnect0 (HttpURLConnection.java:1242)
    at sun.net.www.protocol.http.HttpURLConnection.plainConnect (HttpURLConnection.java:1128)
    at sun.net.www.protocol.http.HttpURLConnection.connect (HttpURLConnection.java:1057)
    at sun.net.www.protocol.http.HttpURLConnection.getInputStream0 (HttpURLConnection.java:1665)
    at sun.net.www.protocol.http.HttpURLConnection.getInputStream (HttpURLConnection.java:1589)
    at java.net.HttpURLConnection.getResponseCode (HttpURLConnection.java:529)
    at org.springdoc.maven.plugin.SpringDocMojo.execute (SpringDocMojo.java:110)
    at org.apache.maven.plugin.DefaultBuildPluginManager.executeMojo (DefaultBuildPluginManager.java:137)
    at org.apache.maven.lifecycle.internal.MojoExecutor.doExecute (MojoExecutor.java:301)
    at org.apache.maven.lifecycle.internal.MojoExecutor.execute (MojoExecutor.java:211)
    at org.apache.maven.lifecycle.internal.MojoExecutor.execute (MojoExecutor.java:165)
    at org.apache.maven.lifecycle.internal.MojoExecutor.execute (MojoExecutor.java:157)
    at org.apache.maven.lifecycle.internal.LifecycleModuleBuilder.buildProject (LifecycleModuleBuilder.java:121)
    at org.apache.maven.lifecycle.internal.LifecycleModuleBuilder.buildProject (LifecycleModuleBuilder.java:81)
    at org.apache.maven.lifecycle.internal.builder.singlethreaded.SingleThreadedBuilder.build (SingleThreadedBuilder.java:56)
    at org.apache.maven.lifecycle.internal.LifecycleStarter.execute (LifecycleStarter.java:127)
    at org.apache.maven.DefaultMaven.doExecute (DefaultMaven.java:294)
    at org.apache.maven.DefaultMaven.doExecute (DefaultMaven.java:192)
    at org.apache.maven.DefaultMaven.execute (DefaultMaven.java:105)
    at org.apache.maven.cli.MavenCli.execute (MavenCli.java:960)
    at org.apache.maven.cli.MavenCli.doMain (MavenCli.java:293)
    at org.apache.maven.cli.MavenCli.main (MavenCli.java:196)
    at jdk.internal.reflect.NativeMethodAccessorImpl.invoke0 (Native Method)
    at jdk.internal.reflect.NativeMethodAccessorImpl.invoke (NativeMethodAccessorImpl.java:77)
    at jdk.internal.reflect.DelegatingMethodAccessorImpl.invoke (DelegatingMethodAccessorImpl.java:43)
    at java.lang.reflect.Method.invoke (Method.java:568)
    at org.codehaus.plexus.classworlds.launcher.Launcher.launchEnhanced (Launcher.java:282)
    at org.codehaus.plexus.classworlds.launcher.Launcher.launch (Launcher.java:225)
    at org.codehaus.plexus.classworlds.launcher.Launcher.mainWithExitCode (Launcher.java:406)
    at org.codehaus.plexus.classworlds.launcher.Launcher.main (Launcher.java:347)
    at jdk.internal.reflect.NativeMethodAccessorImpl.invoke0 (Native Method)
    at jdk.internal.reflect.NativeMethodAccessorImpl.invoke (NativeMethodAccessorImpl.java:77)
    at jdk.internal.reflect.DelegatingMethodAccessorImpl.invoke (DelegatingMethodAccessorImpl.java:43)
    at java.lang.reflect.Method.invoke (Method.java:568)
    at org.apache.maven.wrapper.BootstrapMainStarter.start (BootstrapMainStarter.java:47)
    at org.apache.maven.wrapper.WrapperExecutor.execute (WrapperExecutor.java:156)
    at org.apache.maven.wrapper.MavenWrapperMain.main (MavenWrapperMain.java:72)

My pom file plugin is:

<plugin>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-maven-plugin</artifactId>
    <configuration>
        <jvmArguments>-Dspring.application.admin.enabled=true -Pintegration -Dspringdoc.writer-with-default-pretty-printer=true</jvmArguments>
    </configuration>
    <executions>
        <execution>
            <goals>
                <goal>start</goal>
                <goal>stop</goal>
            </goals>
        </execution>
    </executions>
</plugin>
<plugin>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-maven-plugin</artifactId>
    <version>1.4</version>
    <executions>
        <execution>
            <id>integration-test</id>
            <goals>
                <goal>generate</goal>
            </goals>
        </execution>
    </executions>
</plugin>

And i'm using springdoc-openapi-ui:1.6.9. Am i doing something wrong ?

The following plugins are not marked @threadSafe org.springdoc:springdoc-openapi-maven-plugin:1.1

Hello Team,

We have a maven multi module, where all child modules are independent business modules.
(They could have been separated entirely into multiple standalone projects, but for organizational project, we created one multi module project, with multiple independent children modules inside, anyway, the point is not here).

Since they are independent, and we have some 30 of them, instead of building, running test, generating the openAPI V3 document one project after another (which is very time consuming and waste of computation) we decided to run the pipeline in parallel, with something like:

mvn -T 8C clean install -U -Pintegration -Dspringdoc.writer-with-default-pretty-printer=true javadoc:javadoc checkstyle:checkstyle spotbugs:spotbugs pmd:pmd pmd:cpd org.pitest:pitest-maven:mutationCoverage jacoco:prepare-agent jacoco:report dependency:tree sonar:sonar

We are facing this message when we are doing so:

The following plugins are not marked @threadSafe in myproject:
org.springdoc:springdoc-openapi-maven-plugin:1.1
Enable debug to see more precisely which goals are not marked @threadSafe.
*****************************************************************

Just to confirm if we do not run openAPI V3, we have the parallelism fine.
So, I just wanted to report the issue (or ask for the request for enhancement) to make this plugin thread safe for parallelism documentation generation in the even of maven multi module projects.

Thank you

Error while runnign mvn clean install -> Failed to connect to MBean server at port 9001

Getting below error while running mvn clean install, please help

[ERROR] Failed to execute goal org.springframework.boot:spring-boot-maven-plugin:2.3.0.RELEASE:start (pre-integration-test) on project abcd: Cou
ld not figure out if the application has started: Failed to connect to MBean server at port 9001: Could not invoke shutdown operation: Spring application did
not start before the configured timeout (30000ms -> [Help 1]
[ERROR]
[ERROR] To see the full stack trace of the errors, re-run Maven with the -e switch.

Using below part in pom.xml

org.springdoc springdoc-openapi-ui 1.4.4

</dependencies>

<build>

    <plugins>

        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-compiler-plugin</artifactId>
            <configuration>
                <source>${maven.compiler.source}</source>
                <target>${maven.compiler.target}</target>
                <annotationProcessorPaths>
                    <path>
                        <groupId>org.projectlombok</groupId>
                        <artifactId>lombok</artifactId>
                        <version>${lombok.version}</version>
                    </path>
                    <path>
                        <groupId>org.mapstruct</groupId>
                        <artifactId>mapstruct-processor</artifactId>
                        <version>${mapstruct.version}</version>
                    </path>
                </annotationProcessorPaths>
            </configuration>

        </plugin>
        <plugin>
            <groupId>org.springdoc</groupId>
            <artifactId>springdoc-openapi-maven-plugin</artifactId>
            <version>1.0</version>
            <executions>
                <execution>
                    <id>integration-test</id>
                    <goals>
                        <goal>generate</goal>
                    </goals>
                </execution>
            </executions>
            <configuration>
                <apiDocsUrl>http://localhost:8080/v3/api-docs</apiDocsUrl>
                <outputFileName>openapi.json</outputFileName>
                <outputDir>${project.build.directory}</outputDir>
            </configuration>
        </plugin>
        <plugin>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-maven-plugin</artifactId>
            <configuration>
                <mainClass>aaa.bbb.Abcd</mainClass>
            </configuration>
            <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.jacoco</groupId>
            <artifactId>jacoco-maven-plugin</artifactId>
            <version>${jacoco.version}</version>
            <executions>
                <execution>
                    <goals>
                        <goal>prepare-agent</goal>
                    </goals>
                </execution>
            </executions>
            <configuration>
                <destFile>${sonar.jacoco.reportPath}</destFile>
            </configuration>
        </plugin>
    </plugins>
</build>

Maven plugin does not offer equivalent of 'groupedApiMappings'

The gradle plugin does offer a 'groupedApiMappings'. Could you please tell me if you will implement this in maven plugin in the near future?

404

Hi, I used the maven config from the README but I get a 404 when the plugin tries to fetch the json. here 's a snippet of my CMD:

2020-07-30 14:33:51.008 INFO 13344 --- [lication.main()] DeferredRepositoryInitializationListener : Triggering deferred initialization of Spring Data repositoriesà
2020-07-30 14:33:51.318 INFO 13344 --- [lication.main()] DeferredRepositoryInitializationListener : Spring Data repositories initialized!
2020-07-30 14:33:51.328 INFO 13344 --- [lication.main()] nl.kpnnetwerk.hbo.HboApplication : Started HboApplication in 3.651 seconds (JVM running for 14.689)
[INFO]
[INFO] --- springdoc-openapi-maven-plugin:1.0:generate (generate-openapi) @ hbo-boot ---
2020-07-30 14:33:52.016 INFO 13344 --- [nio-8080-exec-1] o.a.c.c.C.[Tomcat].[localhost].[/] : Initializing Spring DispatcherServlet 'dispatcherServlet'
2020-07-30 14:33:52.016 INFO 13344 --- [nio-8080-exec-1] o.s.web.servlet.DispatcherServlet : Initializing Servlet 'dispatcherServlet'
2020-07-30 14:33:52.021 INFO 13344 --- [nio-8080-exec-1] o.s.web.servlet.DispatcherServlet : Completed initialization in 4 ms
[ERROR] An error has occured: Response code 404
[INFO]

Any ideas? It seems that spring-boot:start returns too early, when the DispatcherServlet is not yet initialized

Are there locations configuration?

I am looking for locations configuration.

when I use 'swagger-maven-plugin', I can use 'locations' configuration
https://github.com/kongchen/swagger-maven-plugin#configuration-for-apisource

I am looking for similar configuration in 'springdoc-openapi-maven-plugin'. but, I cannot find.

Add ability to set title for openapi specification

Plugin does not generate list of objects correctly

Hi,
here is a sample-code:

@ApiModelProperty(notes = "Liste der ProduktgruppenIds")
@JsonProperty("produktgruppenids")
@SiZe (min=1, max=80)
private List< @min(1) @max(100) Long> produktgruppenIds = new ArrayList<>();

The result of the generator is:

_produktgruppenids:

maxItems: 80
minItems: 1
type: array
items:

type: integer
format: int64_

But the result should look like this:

_produktgruppenids:

maxItems: 80
minItems: 1
type: array
items:

maximum: 100
minimum: 1
type: integer
format: int64_

Gibt es eine Möglichkeit, dieses Problem zu beheben?

Hello World

Hey there, I am not a Java or Spring Boot developer but I'm trying to truck my way through all this to get a hello world running for an article, and.... weeeell thing's aren't off to a great start. Hoping somebody here can help.

I've got cloned down https://github.com/springdoc/springdoc-openapi-demos and I'm in springdoc-openapi-spring-boot-2-webmvc. I can run the site with mvn spring-boot:run and if I go to http://localhost:8080 then I see good old Swagger UI running in the browser.

Now, I'd like to be able to run an export command, which will take all the annotations and pump out the YAML, which this plugin should be able to do, but for some reason it's talking about integration-tests and I don't have any of those, as its just a demo application.

Is there a way I can just run a command?

For example, the PHP equivilent is swagger-php, and for that you just run the following:

vendor/bin/openapi -o openapi.json

This means I can enable all sorts of workflows, CI, deployments, etc without needing to wrap ot all up with tests somehow. Could there be a custom maven command I run? Or could it be part of mvn site or something?

For context I'm getting an error when I run mvn integration-test.

2020-09-29 10:06:52.627  INFO 95573 --- [  restartedMain] o.s.b.w.embedded.tomcat.TomcatWebServer  : Tomcat initialized with port(s): 8080 (http)
2020-09-29 10:06:52.636  INFO 95573 --- [  restartedMain] o.apache.catalina.core.StandardService   : Starting service [Tomcat]
2020-09-29 10:06:52.636  INFO 95573 --- [  restartedMain] org.apache.catalina.core.StandardEngine  : Starting Servlet engine: [Apache Tomcat/9.0.38]
2020-09-29 10:06:52.738  INFO 95573 --- [  restartedMain] o.a.c.c.C.[Tomcat].[localhost].[/]       : Initializing Spring embedded WebApplicationContext
2020-09-29 10:06:52.738  INFO 95573 --- [  restartedMain] w.s.c.ServletWebServerApplicationContext : Root WebApplicationContext: initialization completed in 1416 ms
2020-09-29 10:06:53.121  INFO 95573 --- [  restartedMain] o.s.s.concurrent.ThreadPoolTaskExecutor  : Initializing ExecutorService 'applicationTaskExecutor'
2020-09-29 10:06:53.761  INFO 95573 --- [  restartedMain] o.s.b.a.e.web.EndpointLinksResolver      : Exposing 2 endpoint(s) beneath base path '/actuator'
2020-09-29 10:06:53.842  INFO 95573 --- [  restartedMain] o.s.b.d.a.OptionalLiveReloadServer       : LiveReload server is running on port 35729
2020-09-29 10:06:53.886  INFO 95573 --- [  restartedMain] o.s.b.w.embedded.tomcat.TomcatWebServer  : Tomcat started on port(s): 8080 (http) with context path ''
2020-09-29 10:06:53.916  INFO 95573 --- [  restartedMain] org.springdoc.demo.app2.Application      : Started Application in 3.157 seconds (JVM running for 3.959)
2020-09-29 10:07:21.363  INFO 95573 --- [extShutdownHook] o.s.s.concurrent.ThreadPoolTaskExecutor  : Shutting down ExecutorService 'applicationTaskExecutor'
[INFO] ------------------------------------------------------------------------
[INFO] BUILD FAILURE
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  34.347 s
[INFO] Finished at: 2020-09-29T10:07:21+02:00
[INFO] ------------------------------------------------------------------------
[ERROR] Failed to execute goal org.springframework.boot:spring-boot-maven-plugin:2.3.0.RELEASE:start (pre-integration-test) on project springdoc-openapi-spring-boot-2-webmvc: Could not figure out if the application has started: Failed to connect to MBean server at port 9001: Could not invoke shutdown operation: Spring application did not start before the configured timeout (30000ms -> [Help 1]
[ERROR]
[ERROR] To see the full stack trace of the errors, re-run Maven with the -e switch.
[ERROR] Re-run Maven using the -X switch to enable full debug logging.
[ERROR]
[ERROR] For more information about the errors and possible solutions, please read the following articles:
[ERROR] [Help 1] http://cwiki.apache.org/confluence/display/MAVEN/MojoExecutionException

can not generate openapi.json with annotations like @Api/@ApiOperation etc.

Update to a supported version of Spring Boot

Spring Boot 2.0.9.RELEASE is EOL since 2019-03-01 (see https://spring.io/projects/spring-boot#support). Update to a more recent version (2.6.x)

Version 1.4 not deployed in Maven Repository

Hi,
I see in the repo that there's a recent tag named v1.4, but in the maven repository is not available.
https://search.maven.org/artifact/org.springdoc/springdoc-openapi-maven-plugin

Is this caused by an error in the deployment?

Thanks

Can we remove servers path in generated file?

Can we remove some line like servers when using springdoc-openapi-maven-plugin?

actual

{
"openapi" : "3.0.1",
"info" : {
"title" : "Test REST APIs",
"description" : "API
},
"servers" : [ {
"url" : "http://localhost:64994",
"description" : "Generated server url"
} ],
"tags" : ....,
"paths" : ...
}

expect

{
"openapi" : "3.0.1",
"info" : {
"title" : "Test REST APIs",
"description" : "API
},
"tags" : ....,
"paths" : ...
}

Provide configuration for prettyPrint output

Would be awesome if the plugin would offer a configuration for a pretty output (line breaks, indentation).

The outputFileName property should not start with "/"

When the outputFileName property starts with "/", the execution cannot resolve it as an existing directory.
Then the file is not created and no exception is logged.

Plugin do not generate java.util.Date correctly

Hi,
here is a sample-code:

@ApiModelProperty(notes = "Datum an dem das Onboarding zuletzt inaktiv geschaltet wurde")
@JsonProperty("deactivated_date")
@SiZe (max=32)
private Date deactivatedDate;

The generator turns this code into

deactivated_date:
type: string
format: date-time

and not into

deactivated_date:
type: string
format: date-time
maxLength: 32

Is there any way to fix this problem?

Runtime or buildtime?

While upgrading from the old Swagger Springfox library to Springdoc, I was reading this Baeldung article which mentioned this springdoc-openapi Maven Plugin.

The readme.md here on Github starts with:

The aim of springdoc-openapi-maven-plugin is to generate json and yaml OpenAPI description during runtime

though, as I understand it, this plugin is actually providing the documentation at build time instead, as is implicit in the Baeldung article, and clarified by this SO answer by diegomtassis:

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.

It might prevent some confusion if the readme was clear about that :)

Yaml files are still published as json files

Even if I modify the apiDocsUrl to http://localhost:8080/v3/api-docs.yaml and the outputFileName to openapi.yaml. The artifact is still attached as a json file

springdoc.swagger-ui.tryItOutEnabled boolean value is inverted

The application property springdoc.swagger-ui.tryItOutEnabled got an inverted boolean value.

According to the docs setting this property to 'false' should disable the "try it out" feature of swagger, but it's actually the other way round.

Actual build-time capability without a running server

We love springdoc. One thing we find a little annoying though is that to generate the documentation, the server must be running. Essentially the only thing the maven plugin does is calls the URL for the OpenAPI output and persists it to disk. While it checks the box that we can generate the documentation at build time, the overhead of needing to start the server in a dedicated phase of the build is a little much. So a couple of questions:

Is generating the documentation at build time even feasible without the running application? E.g. can the maven mojo somehow look at the annotations to get this data or does that become too much of a dedicated maven solution?
If doing it at build time by looking at the various annotations doesn't work, is it feasible to tie in the call at a different phase? E.g. in https://springdoc.org/#maven-plugin you have the user start/stop the spring boot server but I'm wondering if that can be done inside a test as well so that we don't need a dedicated step to do it?

Plugin does not generate specification

Spring Boot v2.7.6, Spring v5.3.24

            <plugin>
                <groupId>org.springdoc</groupId>
                <artifactId>springdoc-openapi-maven-plugin</artifactId>
                <version>1.4</version>
                <executions>
                    <execution>
                        <id>integration-test</id>
                        <goals>
                            <goal>generate</goal>
                        </goals>
                    </execution>
                </executions>
                <configuration>
                    <!-- See StartupControllerTest -->
                    <apiDocsUrl>http://localhost:8484/docs/api-docs</apiDocsUrl>
                    <outputFileName>openapi.json</outputFileName>
                    <outputDir>${project.basedir}</outputDir>
                    <skip>false</skip>
                </configuration>
            </plugin>

During testing phase of build I can successfully hit the endpoint.
http://localhost:8484/docs/api-docs

{
    "openapi": "3.1.0",
    "info": {
        "title": "UCDP Ingestion",
        "version": "openapi_3_1"
    },
    "servers": [
        {
            "url": "http://localhost:8300/ucdp-ingest",
            "description": "Generated server url"
        }
    ],
    "paths": {
...........

Maven plugin does not offer equivalent of 'forkProperties'

I have a maven build where we would like to use springdoc to pull the generated api spec. Before moving to https we used the 'generate' target of the plugin which worked fine.

Since mandating https we need to be able to specify some additional jvm parameters (ie -Dserver.ssl.trust-store=....) but there is no option to do this (other than probably setting in maven's invocation)

The gradle plugin does offer a 'forkProperties' option which appears to do this. Is there a possibility to add this to the maven plugin?

springdoc / springdoc-openapi-maven-plugin Goto Github PK

springdoc-openapi-maven-plugin's Introduction

Table of Contents

Introduction

Getting Started

Library for springdoc-openapi integration with spring-boot and swagger-ui

Spring-boot with OpenAPI Demo applications.

Source Code for Demo Applications.

Demo Spring Boot 3 Web MVC with OpenAPI 3.

Demo Spring Boot 3 WebFlux with OpenAPI 3.

Demo Spring Boot 3 WebFlux with Functional endpoints OpenAPI 3.

Demo Spring Boot 3 and Spring Cloud Function Web MVC.

Demo Spring Boot 3 and Spring Cloud Function WebFlux.

Demo Spring Boot 3 and Spring Cloud Gateway.

Integration of the library in a Spring Boot 3.x project without the swagger-ui:

Error Handling for REST using @ControllerAdvice

Adding API Information and Security documentation

spring-webflux support with Annotated Controllers

Acknowledgements

Contributors

Additional Support

springdoc-openapi-maven-plugin's People

Contributors

Stargazers

Watchers

Forkers

springdoc-openapi-maven-plugin's Issues

Recommend Projects

Recommend Topics

Recommend Org