openapi-tools/swagger-maven-plugin

Maven plugin to activate the Swagger Core library to generate OpenAPI documentation.

Swagger Maven Plugin

This plugin is intended to use the Swagger Core library to generate OpenAPI documentation from a JAX-RS based REST service with as little change as possible. This allows for @SwaggerDefinition, @ReaderListener and ModelConverters to work the same way as with the core Swagger library.

Status

The plugin is considered production ready. The version 2.x.x of the plugin is supporting generation of OpenAPI version 3 specifications using Swagger 2.x. To generate OpenAPI version 2 specifications using Swagger 1.x use the latest 1.x.x version of the plugin.

Usage

To have Swagger generate the OpenAPI specifications as part of the build add in the plugin to the POM.

<build>
  <plugins>
    ...
    <plugin>
      <groupId>io.openapitools.swagger</groupId>
      <artifactId>swagger-maven-plugin</artifactId>
      <configuration>
        <resourcePackages>
          <resourcePackage>io.openapitools.swagger.example</resourcePackage>
          <resourcePackage>io.openapitools.swagger.example.alternate</resourcePackage>
        </resourcePackages>
        <outputDirectory>${basedir}/target/</outputDirectory>
        <outputFilename>swagger</outputFilename>
        <outputFormats>JSON,YAML</outputFormats>
        <prettyPrint>true</prettyPrint>
      </configuration>
      <executions>
        <execution>
          <goals>
            <goal>generate</goal>
          </goals>
        </execution>
      </executions>
    </plugin>
    ...
  </plugins>
</build>

This will run the generation in the prepare-package lifecycle stage of the Maven build.

Specifying Packages with JAX-RS Endpoints

The packages containing JAX-RS endpoints must be configured using the resourcePackages element. See the minimal configuration above.

Properties of Swagger model

Most general properties of the Swagger model is configurable using the swaggerConfig element. Note this may also be configured through the @OpenAPIDefinition annotation - see Customizing your auto-generated Swagger Definitions.

<plugin>
  <groupId>io.openapitools.swagger</groupId>
  <artifactId>swagger-maven-plugin</artifactId>
  <configuration>
    <swaggerConfig>
      <servers>
        <server>
          <url>https://services.exmple.it/base/path</url>
          <description>Endpoint URL</description>
        </server>
      </servers>
      <info>
        <title>Title</title>
        <version>1.0.0</version>
        <termsOfService>Terms</termsOfService>
        <contact>
          <email>[email protected]</email>
          <name>My Name</name>
          <url>https://google.com</url>
        </contact>
        <license>
          <url>https://license</url>
          <name>MIT</name>
        </license>
        <extensions>
          <x-custom-field-1>my-custom-field-1</x-custom-field-1>
          <x-custom-field-2>my-custom-field-2</x-custom-field-2>
        </extensions>
      </info>
      <descriptionFile>src/test/resources/descriptions.md</descriptionFile>
    </swaggerConfig>

Deploying

The generated OpenAPI specifications may be installed and deployed as Maven artifact. To enable this add the configuration parameter attachSwaggerArtifact.

<plugin>
  <groupId>io.openapitools.swagger</groupId>
  <artifactId>swagger-maven-plugin</artifactId>
  <configuration>
    <attachSwaggerArtifact>true</attachSwaggerArtifact>

Acknowledgement

Thanks to Yukai Kong for his work on Swagger Maven plugin. This plugin is heavily inspired by that.

swagger-maven-plugin's Issues

New release request: Latest Swagger version 2.1.7

Hey Team -- may we get a new release corresponding to Swagger v2.1.7? It has some desirable conveniences and fixes. WR

Class can not found

Hi
try to run with cmd mvn clean install found below error

[ERROR] Failed to execute goal io.openapitools.swagger:swagger-maven-plugin:2.0.2:generate (default) on project some-impl: Execution default of goal io.openapitools.swagger:swagger-maven-plugin:2.0.2:generate failed: A required class was missing while executing io.openapitools.swagger:swagger-maven-plugin:2.0.2:generate: me/streamis/demo/common/ToJson
[ERROR] -----------------------------------------------------
[ERROR] realm =    plugin>io.openapitools.swagger:swagger-maven-plugin:2.0.2
[ERROR] strategy = org.codehaus.plexus.classworlds.strategy.SelfFirstStrategy
[ERROR] urls[0] = file:/Users/stream/.m2/repository/io/openapitools/swagger/swagger-maven-plugin/2.0.2/swagger-maven-plugin-2.0.2.jar
[ERROR] urls[1] = file:/Users/stream/.m2/repository/io/swagger/core/v3/swagger-jaxrs2/2.0.6/swagger-jaxrs2-2.0.6.jar
[ERROR] urls[2] = file:/Users/stream/.m2/repository/org/reflections/reflections/0.9.11/reflections-0.9.11.jar
[ERROR] urls[3] = file:/Users/stream/.m2/repository/org/javassist/javassist/3.22.0-GA/javassist-3.22.0-GA.jar
[ERROR] urls[4] = file:/Users/stream/.m2/repository/io/swagger/core/v3/swagger-models/2.0.6/swagger-models-2.0.6.jar
[ERROR] urls[5] = file:/Users/stream/.m2/repository/io/swagger/core/v3/swagger-annotations/2.0.6/swagger-annotations-2.0.6.jar
[ERROR] urls[6] = file:/Users/stream/.m2/repository/io/swagger/core/v3/swagger-integration/2.0.6/swagger-integration-2.0.6.jar
[ERROR] urls[7] = file:/Users/stream/.m2/repository/io/swagger/core/v3/swagger-core/2.0.6/swagger-core-2.0.6.jar
[ERROR] urls[8] = file:/Users/stream/.m2/repository/com/fasterxml/jackson/dataformat/jackson-dataformat-yaml/2.9.5/jackson-dataformat-yaml-2.9.5.jar
[ERROR] urls[9] = file:/Users/stream/.m2/repository/org/yaml/snakeyaml/1.18/snakeyaml-1.18.jar
[ERROR] urls[10] = file:/Users/stream/.m2/repository/javax/validation/validation-api/1.1.0.Final/validation-api-1.1.0.Final.jar
[ERROR] urls[11] = file:/Users/stream/.m2/repository/com/fasterxml/jackson/jaxrs/jackson-jaxrs-json-provider/2.9.5/jackson-jaxrs-json-provider-2.9.5.jar
[ERROR] urls[12] = file:/Users/stream/.m2/repository/com/fasterxml/jackson/jaxrs/jackson-jaxrs-base/2.9.5/jackson-jaxrs-base-2.9.5.jar
[ERROR] urls[13] = file:/Users/stream/.m2/repository/com/fasterxml/jackson/module/jackson-module-jaxb-annotations/2.9.5/jackson-module-jaxb-annotations-2.9.5.jar
[ERROR] urls[14] = file:/Users/stream/.m2/repository/javax/ws/rs/javax.ws.rs-api/2.1/javax.ws.rs-api-2.1.jar
[ERROR] urls[15] = file:/Users/stream/.m2/repository/org/apache/maven/plugin-tools/maven-plugin-annotations/3.5/maven-plugin-annotations-3.5.jar
[ERROR] urls[16] = file:/Users/stream/.m2/repository/javax/enterprise/cdi-api/1.0/cdi-api-1.0.jar
[ERROR] urls[17] = file:/Users/stream/.m2/repository/org/codehaus/plexus/plexus-utils/3.1.0/plexus-utils-3.1.0.jar
[ERROR] urls[18] = file:/Users/stream/.m2/repository/org/codehaus/plexus/plexus-interpolation/1.25/plexus-interpolation-1.25.jar
[ERROR] urls[19] = file:/Users/stream/.m2/repository/org/sonatype/plexus/plexus-sec-dispatcher/1.4/plexus-sec-dispatcher-1.4.jar
[ERROR] urls[20] = file:/Users/stream/.m2/repository/org/sonatype/plexus/plexus-cipher/1.4/plexus-cipher-1.4.jar
[ERROR] urls[21] = file:/Users/stream/.m2/repository/org/apache/maven/maven-builder-support/3.6.0/maven-builder-support-3.6.0.jar
[ERROR] urls[22] = file:/Users/stream/.m2/repository/org/apache/maven/resolver/maven-resolver-util/1.3.1/maven-resolver-util-1.3.1.jar
[ERROR] urls[23] = file:/Users/stream/.m2/repository/org/apache/maven/shared/maven-shared-utils/3.2.1/maven-shared-utils-3.2.1.jar
[ERROR] urls[24] = file:/Users/stream/.m2/repository/commons-io/commons-io/2.5/commons-io-2.5.jar
[ERROR] urls[25] = file:/Users/stream/.m2/repository/org/eclipse/sisu/org.eclipse.sisu.inject/0.3.3/org.eclipse.sisu.inject-0.3.3.jar
[ERROR] urls[26] = file:/Users/stream/.m2/repository/com/google/inject/guice/4.2.1/guice-4.2.1-no_aop.jar
[ERROR] urls[27] = file:/Users/stream/.m2/repository/aopalliance/aopalliance/1.0/aopalliance-1.0.jar
[ERROR] urls[28] = file:/Users/stream/.m2/repository/org/codehaus/plexus/plexus-component-annotations/1.7.1/plexus-component-annotations-1.7.1.jar
[ERROR] urls[29] = file:/Users/stream/.m2/repository/org/apache/commons/commons-lang3/3.8.1/commons-lang3-3.8.1.jar
[ERROR] urls[30] = file:/Users/stream/.m2/repository/javax/xml/bind/jaxb-api/2.3.0/jaxb-api-2.3.0.jar
[ERROR] urls[31] = file:/Users/stream/.m2/repository/com/fasterxml/jackson/core/jackson-databind/2.9.8/jackson-databind-2.9.8.jar
[ERROR] urls[32] = file:/Users/stream/.m2/repository/com/fasterxml/jackson/core/jackson-annotations/2.9.0/jackson-annotations-2.9.0.jar
[ERROR] urls[33] = file:/Users/stream/.m2/repository/com/fasterxml/jackson/core/jackson-core/2.9.8/jackson-core-2.9.8.jar
[ERROR] urls[34] = file:/Users/stream/.m2/repository/com/google/guava/guava/27.0.1-jre/guava-27.0.1-jre.jar
[ERROR] urls[35] = file:/Users/stream/.m2/repository/com/google/guava/failureaccess/1.0.1/failureaccess-1.0.1.jar
[ERROR] urls[36] = file:/Users/stream/.m2/repository/com/google/guava/listenablefuture/9999.0-empty-to-avoid-conflict-with-guava/listenablefuture-9999.0-empty-to-avoid-conflict-with-guava.jar
[ERROR] urls[37] = file:/Users/stream/.m2/repository/com/google/code/findbugs/jsr305/3.0.2/jsr305-3.0.2.jar
[ERROR] urls[38] = file:/Users/stream/.m2/repository/org/checkerframework/checker-qual/2.5.2/checker-qual-2.5.2.jar
[ERROR] urls[39] = file:/Users/stream/.m2/repository/com/google/errorprone/error_prone_annotations/2.2.0/error_prone_annotations-2.2.0.jar
[ERROR] urls[40] = file:/Users/stream/.m2/repository/com/google/j2objc/j2objc-annotations/1.1/j2objc-annotations-1.1.jar
[ERROR] urls[41] = file:/Users/stream/.m2/repository/org/codehaus/mojo/animal-sniffer-annotations/1.17/animal-sniffer-annotations-1.17.jar
[ERROR] Number of foreign imports: 1
[ERROR] import: Entry[import  from realm ClassRealm[maven.api, parent: null]]
[ERROR]
[ERROR] -----------------------------------------------------
[ERROR] : me.streamis.demo.common.ToJson
[ERROR] -> [Help 1]

Class of `ToJson` is in another maven module, and be dependency by this module.

does plugin can not work cross maven module?

Support for Swagger 1.x annotations

The project being worked on is using the Swagger 1.6.1. Upon executing the plugin, the resultant spec file is missing details like endpoint description etc.

Add the ability to not include all resources

Is your feature request related to a problem? Please describe.
Not related to a problem, but using swagger-core (and its related deps) that generates the output at runtime, you can specify the following config entry:

<param-name>openApi.configuration.readAllResources</param-name>
<param-value>false</param-value>

Which will result in only including the classes/ops that where annotated by an annotation from io.swagger.v3.oas.annotations namespace.

I'll try to create a pull request for it if considered. I think JaxRSScanner the one that should get the changes?

SwaggerComponent: Schema

What's the status of adding schemas to the SwaggerComponent as mentioned here https://github.com/openapi-tools/swagger-maven-plugin/blob/master/src/main/java/io/openapitools/swagger/config/SwaggerComponents.java?

Running plugin returns the error "Scanner SubTypesScanner was not configured"

Hello, I'm trying to set up automatic register of resources with this plugin, but having some difficulty getting it to work with Tomcat. When running mvn verify I'm getting the cryptic error "Scanner SubTypesScanner was not configured". It sounds like something is exploding when trying to use reflection.

I am currently trying with version 2.1.6 of the plugin. For version 1 of the plugin and swagger, the plugin ran properly but it outputted a swagger.json that was nearly empty, so I'm trying v2. I'm using JDK 17, here are the important parts of my pom and my classes, am I doing something majorly wrong?

A couple other questions
* is the swagger annotations dependency required for this to work?
* It used to be with BeanConfig I could tell it to automatically scan for resources, is there a way I need to do that for SwaggerConfiguration?

    <dependency>
        <groupId>io.swagger.core.v3</groupId>
        <artifactId>swagger-jaxrs2</artifactId>
        <version>2.2.0</version>
    </dependency>

  <plugin>
	<groupId>io.openapitools.swagger</groupId>
	<artifactId>swagger-maven-plugin</artifactId>
	<version>2.1.6</version>
	<configuration>
	  <resourcePackages>
		<resourcePackage>org.xyz.boundary</resourcePackage>
	  </resourcePackages>
	  <outputDirectory>${basedir}/target/</outputDirectory>
	  <outputFilename>swagger</outputFilename>
	  <outputFormats>JSON</outputFormats>
	  <prettyPrint>true</prettyPrint>
	</configuration>
	<executions>
	  <execution>
		<goals>
		  <goal>generate</goal>
		</goals>
	  </execution>
	</executions>
  </plugin>

My resource

	@Path("/test")
	@Tag(name = "test", description = "test")
	public class TestResource {
		@GET
		@Operation(summary = "do ting")
		@Produces("application/json")
		public ThingDO getThing() {
			return new ThingDO("testy");
		}
	}

Application config

	@ApplicationPath("/rs")
	public class ApplicationConfig extends Application {
		public ApplicationConfig(@Context ServletConfig config) {
			OpenAPI bc = new OpenAPI();
			Info info = new Info()
				.title("Test")
				.description("better")
				.contact(new Contact().email("[email protected]"))
				.version("1.0");
			bc.info(info);
			SwaggerConfiguration oasConfig = new SwaggerConfiguration()
				.openAPI(bc)
				.prettyPrint(true)
				.resourcePackages(Set.of("org.xyz.boundary"));
			try {
				new JaxrsOpenApiContextBuilder()
	//                .servletConfig(servletConfig)
					.application(this)
					.openApiConfiguration(oasConfig)
					.buildContext(true);
			} catch (OpenApiConfigurationException e) {
				throw new RuntimeException(e.getMessage(), e);
			}
		}
	}

Equivalent plugin for the reporting section of Maven

Hi there, Just want to say this plugin is really good and have been using it in a number of projects both personal and commercial.

I was just wondering if there is any future scope to make it available as a maven reporting plugin so that a OpenAPI spec can be generated and included as part of a Maven site. Or if this is already possible an example on how this is done?

Thanks

Project classes are missing in classpath

Hello,

I have a weird issue when trying to use the plugin. I created a new project using one of the unit-tests poms (generate-mojo-full-pom.xml + dependencies) and sample classes (io.openapitools.swagger.*). However, when I'm trying build a project it generates an empty open-api.yaml:

openapi: 3.0.1
info:
  title: Title
  description: |-
    # Description
    This is some description to be included.
  termsOfService: Terms
  contact:
    name: My Name
    url: https://google.com
    email: [email protected]
  license:
    name: MIT
    url: https://license
  version: 1.0.0
servers:
- url: https://services.example.it/base/path
  description: Example URL

I spent some time debugging the plugin and narrowed it down to io.openapitools.swagger.JaxRSScanner - looks like project classes are simply missing in the classpath despite compilation phase is passed already.

Maven also doesn't run the plugin by default unless I either add an "execution" section in the pom file or call it explicitly:
mvn clean package io.openapitools.swagger:swagger-maven-plugin:generate

Plugin's integration tests work fine for me - project classes are in the classpath.

I use macOS, Maven version is 3.5.4

NullPointerException in 2.1.6

[ERROR] Failed to execute goal io.openapitools.swagger:swagger-maven-plugin:2.1.6:generate (default) on project x: Execution default of goal io.openapitools.swagger:swagger-maven-plugin:2.1.6:generate failed.: NullPointerException -> [Help 1]

OpenApi documentation converts byte[] in array of byte[]

Describe the bug
I generate a java class from a yaml file describing the model.

I have the following model described in the yaml file:

Document:
required:
- documentMetaData
- documentContent
type: "object"
properties:
documentMetaData:
$ref: "#/definitions/DocumentMetaData"
description: "Document type information"
documentContent:
type: string
format: byte
description: "Base64 encoded document content"

This generates the following class which is ok:

public class DownloadDocument {
@JsonProperty("documentMetaData")
private DocumentMetaData documentMetaData;

@JsonProperty("documentContent")
private byte[] documentContent;

But when entering the swagger-ui.html page and trying to get the documentation by click on the link:

it looks like this:

"DownloadDocument": {
"required": [
"documentContent",
"documentMetaData"
],
"type": "object",
"properties": {
"documentMetaData": {
"$ref": "#/components/schemas/DocumentMetaData"
},
"documentContent": {
"type": "array",
"items": {
"type": "string",
"format": "byte"
}
}
The document content which is a byte[] is documented as an array of byte[] and when using this description in other app to generate an api client it generates a List<byte[]>.

I would expect the following format also in the OpenApi Specification:
"documentContent": {
"type": "string",
"format": "byte"
}**

Can you please advice if this is a bug or if not how can be resolved?

Field ordering not maintained in generated object descriptions

Describe the bug
On subsequent executions on the same codebase the ordering of attributes is random. This leads to incompatible constructor signatures in generated client code.

To Reproduce

• create maven project that generates JSON/YAML api descriptions for some Java source
• execute the build several times (keeping the generated yaml/json api descriptions)
• compare generated api descriptions

Expected behavior

• API descriptions generated by all the executions are identical

Additional context
Randomizing attribute ordering leads to different constructor signatures for object in generated client code. This requires changes to the source code using generated client every time the client is generated based on regenerated API description.

Bug related to endpoints with the same path but different consumes (produces)

Hi, imagine there are two methods which differ by the consumes (produces) value:

@Get
@Path("/path")
@Consumes(“application/json“)
@Produces(“application/json“)
public Response methodOne(…) {…}

@Get
@Path("/path")
@Consumes(“application/xml“)
@Produces(“application/json“)
public Response methodTwo(…) {…}

In this case the resulting documentation contains either methodOne or methodTwo but not two methods at the same time.

The version of plugin I am using is 2.1.5.
Is this a known issue and does it have any solution?
Thanks a lot in advance!

swagger-maven-plugin in the version 2.1.1 is not working with swagger-core (swagger-jaxrs2) version 2.1.0

Describe the bug
swagger-maven-plugin in the version 2.1.1 is not working with swagger-core (swagger-jaxrs2) version 2.1.0
If you try to pass the swagger-core (swagger-jaxrs2) version 2.1.0 to the plugin as described in 'To Reproduce', the plugin uses the new passed version but if you compile it with maven it fails with the following error

mvn clean compile
......
[ERROR] Failed to execute goal io.openapitools.swagger:swagger-maven-plugin:2.1.1:generate (default) on project XYZ: Execution default of goal io.openapitools.swagger:swagger-maven-plugin:2.1.1:generate failed: A required class was missing while executing io.openapitools.swagger:swagger-maven-plugin:2.1.1:generate: org/reflections/Configuration

You can fix this error adding two following additional libraries to the plugin configuration.

<dependency>
    <groupId>org.reflections</groupId>
    <artifactId>reflections</artifactId>
    <version>0.9.11</version>
    <exclusions>
    	<exclusion>
        	<groupId>org.javassist</groupId>
            <artifactId>javassist</artifactId>
        </exclusion>
    </exclusions>
</dependency>
<dependency>
	<groupId>com.fasterxml.jackson.core</groupId>
    <artifactId>jackson-databind</artifactId>
    <version>2.10.0.pr3</version>
</dependency>

To Reproduce
Pass swagger-core in version 2.1.0 to the plugin configuration, for example like this

<plugin>
	<groupId>io.openapitools.swagger</groupId>
    <artifactId>swagger-maven-plugin</artifactId>
    <version>2.1.1</version>
    <configuration>
        <outputDirectory>${project.build.directory}/${project.artifactId}</outputDirectory>
        <outputFormats>JSON,YAML</outputFormats>
        <prettyPrint>true</prettyPrint>
    </configuration>
    <executions>
    	<execution>
        	<goals>
            	<goal>generate</goal>
            </goals>
    	</execution>
    </executions>
    <dependencies>
    	<dependency>
        	<groupId>io.swagger.core.v3</groupId>
                <artifactId>swagger-jaxrs2</artifactId>
                <version>2.1.0</version>
        </dependency>
    </dependencies>
</plugin>

Build your project with maven mvn clean compile.

Expected behavior
It would be great if the new version could use swagger-core (swagger-jaxrs2) in version >=2.1.0

Getting a NullPointerException at java.util.TreeMap.putAll (TreeMap:312)

Describe the bug
I'm getting a NullPointerException at java.util.TreeMap.putAll (TreeMap:312) after adding the plugin to my project.

[ERROR] Failed to execute goal io.openapitools.swagger:swagger-maven-plugin:2.1.5:generate (default) on project my-service: Execution default of goal io.openapitools.swagger:swagger-maven-plugin:2.1.5:generate failed.: NullPointerException -> [Help 1]
org.apache.maven.lifecycle.LifecycleExecutionException: Failed to execute goal io.openapitools.swagger:swagger-maven-plugin:2.1.5:generate (default) on project my-service: Execution default of goal io.openapitools.swagger:swagger-maven-plugin:2.1.5:generate failed.
    at org.apache.maven.lifecycle.internal.MojoExecutor.execute (MojoExecutor.java:215)
    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:957)
    at org.apache.maven.cli.MavenCli.doMain (MavenCli.java:289)
    at org.apache.maven.cli.MavenCli.main (MavenCli.java:193)
    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:566)
    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)
Caused by: org.apache.maven.plugin.PluginExecutionException: Execution default of goal io.openapitools.swagger:swagger-maven-plugin:2.1.5:generate failed.
    at org.apache.maven.plugin.DefaultBuildPluginManager.executeMojo (DefaultBuildPluginManager.java:148)
    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:957)
    at org.apache.maven.cli.MavenCli.doMain (MavenCli.java:289)
    at org.apache.maven.cli.MavenCli.main (MavenCli.java:193)
    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:566)
    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)
Caused by: java.lang.NullPointerException
    at java.util.TreeMap.putAll (TreeMap.java:312)
    at java.util.TreeMap.<init> (TreeMap.java:185)
    at io.openapitools.swagger.OpenAPISorter.sortPaths (OpenAPISorter.java:50)
    at io.openapitools.swagger.OpenAPISorter.sort (OpenAPISorter.java:41)
    at io.openapitools.swagger.GenerateMojo.execute (GenerateMojo.java:127)
    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:957)
    at org.apache.maven.cli.MavenCli.doMain (MavenCli.java:289)
    at org.apache.maven.cli.MavenCli.main (MavenCli.java:193)
    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:566)
    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)
[ERROR] 
[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/PluginExecutionException

To Reproduce
This is how I defined the plugin in my POM file:

<plugin>
  <groupId>io.openapitools.swagger</groupId>
  <artifactId>swagger-maven-plugin</artifactId>
  <version>2.1.5</version>
  <configuration>
      <resourcePackages>
          <resourcePackage>com.example.my.service.common</resourcePackage>
          <resourcePackage>com.example.my.service.controller</resourcePackage>
      </resourcePackages>
      <outputDirectory>${basedir}/target/</outputDirectory>
      <outputFilename>swagger</outputFilename>
      <outputFormats>JSON,YAML</outputFormats>
      <prettyPrint>true</prettyPrint>

      <!-- This information will be included in the output swagger file -->
      <swaggerConfig>
          <servers>
              <server>
                  <url>https://prod.my-server.com</url>
                  <description>Production Server</description>
              </server>
              <server>
                  <url>https://dev.my-server.com</url>
                  <description>Development Server</description>
              </server>
          </servers>
          <info>
              <title>My Service</title>
              <version>${project.version}</version>
              <description>
                  This service provides blah blah
              </description>
              <termsOfService>
                  TBD
              </termsOfService>
              <contact>
                  <email>[email protected]</email>
                  <name>Someone</name>
                  <url>mailto:[email protected]</url>
              </contact>
              <license>
                  <url>TBD</url>
                  <name>TBD</name>
              </license>
          </info>
      </swaggerConfig>

  </configuration>
  <executions>
      <execution>
          <goals>
              <goal>generate</goal>
          </goals>
      </execution>
  </executions>
</plugin>

Expected behavior
I expected the project to build properly and generate the JSON and YAML files.

Additional context
I'm experiencing this issue with versions from 2.1.3 to 2.1.6 (latest as of report date). It works with 2.1.2.

Creating component definition

I'm using the default configuration in my pom:

<configuration>
    <resourcePackages>
        <resourcePackage>com.myapp.resource</resourcePackage>
    </resourcePackages>
    <outputDirectory>${basedir}/target/</outputDirectory>
    <outputFilename>my-api</outputFilename>
    <outputFormats>JSON,YAML</outputFormats>
    <prettyPrint>true</prettyPrint>
</configuration>

I need to manually define certain of the external component schemas because our code-gen library is not able to understand what this plugin generates. For that reason, for such modules, I'm annotating the component with @Schema(ref = "PackageName"). This plugin then successfully generates the open-api definition and references the components correctly.

However, the component itself becomes a self reference component:

components:
  schema:
    PackageName:
      $ref: '#/components/schemas/PackageName'

Instead, I want to be able to define this component myself so I can set it to be

components:
  schema:
    PackageName:
      type: object
      x-jvm-type: PackageName
      description: My awesome description
      example: 1234

I created a feature request here #66 since securitySchema can now be defined in the pom configuration. In the meantime, I wanted to know if there are any workarounds to get this to work?

Link provided to swagger blog is for OpenApi 2.0 not 3.0

The link in the README.md is for version 2.0 of the spec
https://github.com/openapi-tools/swagger-maven-plugin#properties-of-swagger-model
https://swagger.io/blog/api-development/customizing-your-auto-generated-swagger-definition/

specifically the properties basePath, schemes, host were replaced by "servers" config as described here: https://swagger.io/docs/specification/api-host-and-base-path/

Did cost me some time to realize this which cost me way too long.

It would be nice to document all implemented config as not everything is implemented yet. In #58 there was an TODO added which states some of the missing properties: https://github.com/openapi-tools/swagger-maven-plugin/pull/58/files#diff-ad93ce60fb68b7e1422be9ba9083ec58

attachSwaggerArtifact ignores outputFilename

Describe the bug
When using attachSwaggerArtifact = true the filename of the maven artifact is always ...swagger.json and ...swagger.yaml instead of the configured outputFilename.

To Reproduce
Maven project with swagger-maven-plugin configured with outputFilename = "openapi" and attachSwaggerArtifact = "true" and build the maven project.

Expected behavior
The outputFilename is used instead of "swagger"

@ApplicationPath seems to be ignored by the plugin

The swagger maven plugin does not take the javax.ws.rs.Application class and @ApplicationPath and its base URI into consideration when it generates the documentation. All paths that are generated by the plugin are missing the base URI provided by the annotation. Documentation generated by swagger JAX-RS resources handle this correctly.

To demonstrate this, I have set up a sample project that uses both the swagger resource and this plugin to create the openapi documentation. I have also attached the outputs they provide (in json format), wherer the difference can be clearly seen.

The reason for the difference is that the GenerateMojo instantiates the swagger Reader instance, but it does not provide it with the instance of javax.ws.rs.Application (possibly annotated with @ApplicationPath). As a consequence of this, the Reader produces the OpenApi instance, but ignores the Application. Luckily, it is possible to work around this limitation by creating custom ReaderListener (however, it must be annotated by @OpenAPIDefinition, otherwise it is not picked up by the plugin) and set the application class to the provided Reader by calling reader#setApplication(...)), however, I think that the plugin could somehow support this out of the box. My thoughs:

• an additional parameter could be added to the plugin configuration, where the fully qualified name of the Application class could be specified
• a classpath scanning could be performed to find the class automatically

Do you think this might be useful?

The json documentations for comparison:
swagger_docs.zip

The sample project:
swagger-maven-plugin-sample-project.zip

Any plans for adding support for Spring MVC applications?

Hey, I was wondering if support for Spring apps is on the table, like it is supported in the case of original plugin by Kongchen. Thanks a lot! @strohel

Problem implementing oauth security scheme

The problem is with the security definition.

openapi: 3.0.1
    info:
      title: My sample API
      description: |-
        Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor inc
    
        

<a href="example.com">example.com</a>
      version: 1.0.0
    security:
      - /myapp-auth.json: []
    tags:
      - name: name1
        description: description1
      - name: name2
        description: description2
      
    

paths:
      /api/v1/path1:
        post:
          tags:
            - Files
          summary: sample summary
          description: some description...

The documentation of the plugin is very limited and I'm not able to use the correct syntax i guess. This is what i am doing

<plugin>
            <groupId>io.openapitools.swagger</groupId>
            <artifactId>swagger-maven-plugin</artifactId>
            <version>2.1.6</version>
            <configuration>
                <resourcePackages>
                    <resourcePackage>com.example.controller</resourcePackage>
                </resourcePackages>
                <outputDirectory>${basedir}/src/main/resources/</outputDirectory>
                <outputFilename>swagger-file</outputFilename>
                <outputFormats>JSON</outputFormats>
                <prettyPrint>true</prettyPrint>
                <swaggerConfig>
                    <descriptionFile>${basedir}/src/main/resources/description.txt</descriptionFile>
                    <info>
                        <title>myapp API</title>
                        <version>${api.version}</version>
                    </info>
                   <securityRequirements>
                        <securityRequirement>
                            <entries>
                                <entry>
                                    <name>/myApp-auth.json</name>
                                </entry>
                            </entries>
                        </securityRequirement> 
                    </securityRequirements>
                </swaggerConfig>
            </configuration>
            <executions>
                <execution>
                    <goals>
                        <goal>generate</goal>
                    </goals>
                </execution>
            </executions>
        </plugin>

below is my myApp.json file

{
  "myApp_auth": {
    "type": "oauth2",
    "tokenUrl": "example.com",
    "flow": "password",
    "scopes": {
      "read.pet": "read scope",
      "write.pet": "modify scope",
      ...

    }
  }
}

The generation-result is not deterministic

Describe the bug
I have a controller-class.
I'm able to generate json and yaml.
But every time I run the plugin the result looks different to the prev. one.
This is not so helpfull because I put the result into my git-repo.

<plugin>
        <groupId>io.swagger.core.v3</groupId>
        <artifactId>swagger-maven-plugin</artifactId>
        <version>${swagger-maven-plugin.version}</version>
        <configuration>
          <outputPath>${basedir}/src/openapi/</outputPath>
          <outputFileName>cc-${api.version}</outputFileName>
          <outputFormat>JSONANDYAML</outputFormat>
          <prettyPrint>TRUE</prettyPrint>
          <attachSwaggerArtifact>true</attachSwaggerArtifact>
          <resourceClasses>
            <resourceClasse>com.siemens.spice.cc.rest.service.ConfigurationController</resourceClasse>
          </resourceClasses>
        </configuration>
        <executions>
          <execution>
            <phase>compile</phase>
            <goals>
              <goal>resolve</goal>
            </goals>
          </execution>
        </executions>
      </plugin>

To Reproduce
Simply run the generation multiple time without any change.

Expected behavior
The generated json/yaml must create always the same output.

I tried to "fix" this behavior in io.openapitools.swagger.GenerateMojo.execute()

OpenAPI swagger = reader.read(reflectiveScanner.classes());

// XXX .... try to bring all the props in a "stable" order ...
swagger.paths(sortPaths(swagger.getPaths()));
swagger.components(sortComponents(swagger.getComponents()));

...

private Components sortComponents(Components components) {
        if (components==null)
            return null;
        Components r = new Components();
        r.setSchemas(sort(components.getSchemas()));
        return r;
    }

    private io.swagger.v3.oas.models.Paths sortPaths(io.swagger.v3.oas.models.Paths paths) {
        if (paths==null)
            return null;
        io.swagger.v3.oas.models.Paths r = new io.swagger.v3.oas.models.Paths();
        r.putAll(sort(paths));
        return r;
    }

    private <K extends Comparable<K>, V> Map<K, V> sort(Map<K, V> map) {
        return map
                .entrySet()
                .stream()
                .sorted(Map.Entry.comparingByKey())
                .collect(Collectors.toMap(Map.Entry::getKey, Map.Entry::getValue));
    }
``´


But I'm not sure if this is the right direction to go :)

Generate open api v3 spec from Spring MVC RestControllers code

Is your feature request related to a problem? Please describe.
We need to be able to extract the openapi specs from Spring MVC RestControllers code dinamically

Describe the solution you'd like
It would be nice to have the specs generated (json, yaml) from Spring MVC RestControllers with v3 annotations at build time.

Describe alternatives you've considered
We've tried Kongchen's plugin but seems like it does not support open api v3 specs yet

Additional context

Add support for vendor extensions in the 'info' section

Like in the previous version of the Swagger at plugin https://github.com/kongchen/swagger-maven-plugin, it would be nice to support vendor extensions in the 'info' section of the plugin.

I can take care of that and open a PR, but I'm waiting for some official approval from my employer to be able to work on that project.

support nested extensions

The new extension feature since version 2.0.2 allows to define entries like this:

<info>
  <title>My API</title>
  <extensions>
    <x-my-extension>anything</x-my-extension>
  </extensions>
</info>

Unfortunately, nested values inside an extension are ignored and rendered as null values.

<info>
  <title>My API</title>
  <extensions>
    <x-my-extension>
      <nested>anything</nested>
    </x-my-extension>
  </extensions>
</info>

I kindly ask to add support for such nested extensions.

reflection urls from project

Trying to use this with a project with swagger-core/swagger-jaxrs2 2.0.5 annotations.

I found the output to be missing every single api and only including the Info data from the plugin specification.

I've been debugging my way through this and I've found that when the Configuration Builder builds it doesn't include any of the URLs for the project, so it wouldn't be able to find any project classes under the listed resourcePackages.

I altered the plugin code to ensure that the plugin picks up the project URLs, and also had to set the config ClassLoaders.

This has then led to the project classes being loaded, but unfortunately I'm now at a dead end when a project class that very clearly is annotated with javax.ws.rs.Path (and it shows in the annotationData on reflection), responds to ReflectionUtils.getAnnotation(cls, javax.ws.rs.Path.class) with null.

Now, I assume I'm doing something quite wrong here (and I'm by no means a reflection guru) as my expectation is that the plugin would run during the build process, run over the classes found under the resourcePackages and an OAS 3.0 would come out the other side, similar to how the kongchen plugin works for OAS 2.0, but it doesn't seem to want to play ball for me.

Plugin configuration in case you're curious

         <plugin>
                <groupId>io.openapitools.swagger</groupId>
                <artifactId>swagger-maven-plugin</artifactId>
                <version>2.0.0</version>
                <configuration>
                    <resourcePackages>
                        <resourcePackage>com.my.api</resourcePackage>
                    </resourcePackages>
                    <outputFormats>
                        <outputFormat>JSON</outputFormat>
                        <outputFormat>YAML</outputFormat>
                    </outputFormats>
                    <outputDirectory>target/api</outputDirectory>
                    <outputFilename>swagger</outputFilename>
                </configuration>
            </plugin>

(edits for language, too much reflection debugging seems to remove my ability to type)

modelSubstitute does not work

modelSubstitute does not seem to work, and I cannot find any reference to it in the source code. How can I substitute a model here?

parent packeage are not supported

In resourcePackages i have to put every package I use.
For example if the Api class is in com.foo.bar but the response object is in com. foo.foo i can't put just com.foo in the resourcePackages .
Could it be useful change this line of code resourcePackages.contains(cls.getPackage().getName()) in JaxRSScanner to enable parent package

a required class is missing during build

Hi,

I got the following error while trying to build the project and generate the api document. The api document was not generated.

Execution default of goal io.openapitools.swagger:swagger-maven-plugin:2.0.3:generate failed: A required class was missing while executing io.openapitools.swagger:swagger-maven-plugin:2.0.3:generate: org/apache/deltaspike/data/api/EntityRepository

However, the class file EntityRepository exists

Do you see any reason?

Thanks,

Wayne

Some project dependencies are missing when scanning the project

When the swagger-maven-plugin scans the project for swagger resources, the classloader it uses to load classes is missing the scanned project's dependencies, and thus may fail with ClassNotFoundException or similar. This can be worked around by explicitly listing all dependencies of the project in plugin's dependencies section, but for large projects there can be many dependencies, so adding all required ones may be tedious, and the plugin should handle this automatically if possible.

I have put up a simple project that demonstrates this: swagger-maven-project-with-dependencies.zip

I think this can be solved by not adding just project.getBuild().getOutputDirectory() to the URLClassLoader, but also the resources provided by project.getCompileClasspathElements() and project.getRuntimeClasspathElements().

Add support for OpenAPI v3

Swagger 2.x.x is out with support for OpenAPI specification v3. The Maven plugin should be updated to support this.

Missing class javax.servlet.ServletConfig

<plugin>
        <groupId>io.openapitools.swagger</groupId>
        <artifactId>swagger-maven-plugin</artifactId>
        <version>2.1.2</version>
        <configuration>
          <outputPath>${basedir}/src/openapi/</outputPath>
          <outputFileName>cc-${api.version}</outputFileName>
          <outputFormat>JSONANDYAML</outputFormat>
          <prettyPrint>TRUE</prettyPrint>
          <attachSwaggerArtifact>true</attachSwaggerArtifact>
          <resourceClasses>
            <resourceClasse>com.siemens.spice.cc.rest.service.ConfigurationController</resourceClasse>
            <resourceClasse>com.siemens.spice.cc.rest.service.HistoryController</resourceClasse>
            <resourceClasse>com.siemens.spice.cc.rest.service.SettingsController</resourceClasse>
            <resourceClasse>com.siemens.spice.cc.rest.service.ProductsController</resourceClasse>
          </resourceClasses>
        </configuration>
        <executions>
          <execution>
            <phase>process-classes</phase>
            <goals>
              <goal>generate</goal>
            </goals>
          </execution>
        </executions>
      </plugin>
``´

[ERROR] Failed to execute goal io.openapitools.swagger:swagger-maven-plugin:2.1.2:generate (default) on project rest-service: Execution default of goal io.openapitools.swagger:swagger-maven-plugin:2.1.2:generate failed: A required class was missing while executing io.openapitools.swagger:swagger-maven-plugin:2.1.2:generate: Ljavax/servlet/ServletConfig;
[ERROR] -----------------------------------------------------
[ERROR] realm =    plugin>io.openapitools.swagger:swagger-maven-plugin:2.1.2
[ERROR] strategy = org.codehaus.plexus.classworlds.strategy.SelfFirstStrategy
[ERROR] urls[0] = file:/D:/Dev/ApacheMaven/repository/io/openapitools/swagger/swagger-maven-plugin/2.1.2/swagger-maven-plugin-2.1.2.jar
[ERROR] urls[1] = file:/D:/Dev/ApacheMaven/repository/io/swagger/core/v3/swagger-jaxrs2/2.1.0/swagger-jaxrs2-2.1.0.jar
[ERROR] urls[2] = file:/D:/Dev/ApacheMaven/repository/io/github/classgraph/classgraph/4.6.32/classgraph-4.6.32.jar
[ERROR] urls[3] = file:/D:/Dev/ApacheMaven/repository/org/javassist/javassist/3.22.0-GA/javassist-3.22.0-GA.jar
[ERROR] urls[4] = file:/D:/Dev/ApacheMaven/repository/io/swagger/core/v3/swagger-models/2.1.0/swagger-models-2.1.0.jar
[ERROR] urls[5] = file:/D:/Dev/ApacheMaven/repository/io/swagger/core/v3/swagger-annotations/2.1.0/swagger-annotations-2.1.0.jar
[ERROR] urls[6] = file:/D:/Dev/ApacheMaven/repository/io/swagger/core/v3/swagger-integration/2.1.0/swagger-integration-2.1.0.jar
[ERROR] urls[7] = file:/D:/Dev/ApacheMaven/repository/io/swagger/core/v3/swagger-core/2.1.0/swagger-core-2.1.0.jar
[ERROR] urls[8] = file:/D:/Dev/ApacheMaven/repository/com/fasterxml/jackson/dataformat/jackson-dataformat-yaml/2.10.1/jackson-dataformat-yaml-2.10.1.jar
[ERROR] urls[9] = file:/D:/Dev/ApacheMaven/repository/org/yaml/snakeyaml/1.24/snakeyaml-1.24.jar
[ERROR] urls[10] = file:/D:/Dev/ApacheMaven/repository/com/fasterxml/jackson/datatype/jackson-datatype-jsr310/2.10.1/jackson-datatype-jsr310-2.10.1.jar
[ERROR] urls[11] = file:/D:/Dev/ApacheMaven/repository/javax/validation/validation-api/1.1.0.Final/validation-api-1.1.0.Final.jar
[ERROR] urls[12] = file:/D:/Dev/ApacheMaven/repository/com/fasterxml/jackson/jaxrs/jackson-jaxrs-json-provider/2.10.1/jackson-jaxrs-json-provider-2.10.1.jar
[ERROR] urls[13] = file:/D:/Dev/ApacheMaven/repository/com/fasterxml/jackson/jaxrs/jackson-jaxrs-base/2.10.1/jackson-jaxrs-base-2.10.1.jar
[ERROR] urls[14] = file:/D:/Dev/ApacheMaven/repository/com/fasterxml/jackson/module/jackson-module-jaxb-annotations/2.10.1/jackson-module-jaxb-annotations-2.10.1.jar
[ERROR] urls[15] = file:/D:/Dev/ApacheMaven/repository/jakarta/xml/bind/jakarta.xml.bind-api/2.3.2/jakarta.xml.bind-api-2.3.2.jar
[ERROR] urls[16] = file:/D:/Dev/ApacheMaven/repository/jakarta/activation/jakarta.activation-api/1.2.1/jakarta.activation-api-1.2.1.jar
[ERROR] urls[17] = file:/D:/Dev/ApacheMaven/repository/javax/ws/rs/javax.ws.rs-api/2.1/javax.ws.rs-api-2.1.jar
[ERROR] urls[18] = file:/D:/Dev/ApacheMaven/repository/org/apache/maven/plugin-tools/maven-plugin-annotations/3.5/maven-plugin-annotations-3.5.jar
[ERROR] urls[19] = file:/D:/Dev/ApacheMaven/repository/javax/enterprise/cdi-api/1.0/cdi-api-1.0.jar
[ERROR] urls[20] = file:/D:/Dev/ApacheMaven/repository/org/codehaus/plexus/plexus-utils/3.1.0/plexus-utils-3.1.0.jar
[ERROR] urls[21] = file:/D:/Dev/ApacheMaven/repository/org/codehaus/plexus/plexus-interpolation/1.25/plexus-interpolation-1.25.jar
[ERROR] urls[22] = file:/D:/Dev/ApacheMaven/repository/org/sonatype/plexus/plexus-sec-dispatcher/1.4/plexus-sec-dispatcher-1.4.jar
[ERROR] urls[23] = file:/D:/Dev/ApacheMaven/repository/org/sonatype/plexus/plexus-cipher/1.4/plexus-cipher-1.4.jar
[ERROR] urls[24] = file:/D:/Dev/ApacheMaven/repository/org/apache/maven/maven-builder-support/3.6.0/maven-builder-support-3.6.0.jar
[ERROR] urls[25] = file:/D:/Dev/ApacheMaven/repository/org/apache/maven/resolver/maven-resolver-util/1.3.1/maven-resolver-util-1.3.1.jar
[ERROR] urls[26] = file:/D:/Dev/ApacheMaven/repository/org/apache/maven/shared/maven-shared-utils/3.2.1/maven-shared-utils-3.2.1.jar
[ERROR] urls[27] = file:/D:/Dev/ApacheMaven/repository/commons-io/commons-io/2.5/commons-io-2.5.jar
[ERROR] urls[28] = file:/D:/Dev/ApacheMaven/repository/org/eclipse/sisu/org.eclipse.sisu.inject/0.3.3/org.eclipse.sisu.inject-0.3.3.jar
[ERROR] urls[29] = file:/D:/Dev/ApacheMaven/repository/com/google/inject/guice/4.2.1/guice-4.2.1-no_aop.jar
[ERROR] urls[30] = file:/D:/Dev/ApacheMaven/repository/aopalliance/aopalliance/1.0/aopalliance-1.0.jar
[ERROR] urls[31] = file:/D:/Dev/ApacheMaven/repository/org/codehaus/plexus/plexus-component-annotations/1.7.1/plexus-component-annotations-1.7.1.jar
[ERROR] urls[32] = file:/D:/Dev/ApacheMaven/repository/org/apache/commons/commons-lang3/3.8.1/commons-lang3-3.8.1.jar
[ERROR] urls[33] = file:/D:/Dev/ApacheMaven/repository/org/reflections/reflections/0.9.11/reflections-0.9.11.jar
[ERROR] urls[34] = file:/D:/Dev/ApacheMaven/repository/javax/xml/bind/jaxb-api/2.3.0/jaxb-api-2.3.0.jar
[ERROR] urls[35] = file:/D:/Dev/ApacheMaven/repository/com/fasterxml/jackson/core/jackson-databind/2.10.1/jackson-databind-2.10.1.jar
[ERROR] urls[36] = file:/D:/Dev/ApacheMaven/repository/com/fasterxml/jackson/core/jackson-annotations/2.10.1/jackson-annotations-2.10.1.jar
[ERROR] urls[37] = file:/D:/Dev/ApacheMaven/repository/com/fasterxml/jackson/core/jackson-core/2.10.1/jackson-core-2.10.1.jar
[ERROR] urls[38] = file:/D:/Dev/ApacheMaven/repository/com/google/guava/guava/28.1-jre/guava-28.1-jre.jar
[ERROR] urls[39] = file:/D:/Dev/ApacheMaven/repository/com/google/guava/failureaccess/1.0.1/failureaccess-1.0.1.jar
[ERROR] urls[40] = file:/D:/Dev/ApacheMaven/repository/com/google/guava/listenablefuture/9999.0-empty-to-avoid-conflict-with-guava/listenablefuture-9999.0-empty-to-avoid-conflict-with-guava.jar
[ERROR] urls[41] = file:/D:/Dev/ApacheMaven/repository/com/google/code/findbugs/jsr305/3.0.2/jsr305-3.0.2.jar
[ERROR] urls[42] = file:/D:/Dev/ApacheMaven/repository/org/checkerframework/checker-qual/2.8.1/checker-qual-2.8.1.jar
[ERROR] urls[43] = file:/D:/Dev/ApacheMaven/repository/com/google/errorprone/error_prone_annotations/2.3.2/error_prone_annotations-2.3.2.jar
[ERROR] urls[44] = file:/D:/Dev/ApacheMaven/repository/com/google/j2objc/j2objc-annotations/1.3/j2objc-annotations-1.3.jar
[ERROR] urls[45] = file:/D:/Dev/ApacheMaven/repository/org/codehaus/mojo/animal-sniffer-annotations/1.18/animal-sniffer-annotations-1.18.jar
[ERROR] Number of foreign imports: 1
[ERROR] import: Entry[import  from realm ClassRealm[maven.api, parent: null]]
[ERROR]
[ERROR] -----------------------------------------------------
[ERROR] : javax.servlet.ServletConfig
[ERROR] -> [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/PluginContainerException

$ mvn -version
Apache Maven 3.6.3 (cecedd343002696d0abb50b32b541b8a6ba2883f)
Maven home: D:\Dev\ApacheMaven\current-maven
Java version: 1.8.0_252, vendor: Azul Systems, Inc., runtime: D:\Dev\Java\jdk8x64\jre
Default locale: de_DE, platform encoding: Cp1252
OS name: "windows 10", version: "10.0", arch: "amd64", family: "windows"

byte[] not correctly handled by openapi converter

I tried to generate an OpenApi-Definition from a java-class.

I run into problems with byte-arrays. Those are generated as openapi-arrays, but the openapi-tools create java-lists for openapi-arrays.

The OpenApi-Generator should instead generate a string with format binary according to the swagger-spec (https://swagger.io/docs/specification/data-models/data-types/, section strings)

Please find the sample code in the attachted openapi-byte-array.zip

It contains also a maven-pom-template for configuring the maven-swagger-plugin.

I ran the plugin from command line with

mvn io.swagger.core.v3:swagger-maven-plugin:2.0.7:resolve
The expected openapi-output for a byte[] is:

        "binaryContent" : {
          "type" : "string",
          "format": "byte", 
          "description" : "base64 encoded binary content."
        }

This would would work with the openapi-generator-plugin [https://github.com/OpenAPITools/]:

    <plugin>
        <groupId>org.openapitools</groupId>
        <artifactId>openapi-generator-maven-plugin</artifactId>
        <version>3.3.3</version>
        <executions>
          <execution>
            <id>8djh-jom-client</id>
            <goals>
              <goal>generate</goal>
            </goals>
            <configuration>
              <inputSpec>${project.basedir}/src/main/openapi/openapi.json</inputSpec>
              <generateDirectory>${project.build.directory}/generated-sources</generateDirectory>
              <generatorName>java</generatorName>
              <generateApiTests>false</generateApiTests>
              <generateModelTests>false</generateModelTests>
              
              <configOptions>
                <sourceFolder>test-rest-client</sourceFolder>
                <apiPackage>test.api</apiPackage>
                <modelPackage>test.model</modelPackage>
                <library>resttemplate</library>
                <dateLibrary>java8</dateLibrary>
              </configOptions>
            </configuration>
          </execution>
        </executions>
      </plugin>

do i miss something? Do i need to register a converter ?

NullPointerException if no JaxRS/OpenApi classes found

Motivation: When creating a project from scratch i want wo add swagger even before building the first webservice.

Currently if no class is found with @path or @OpenAPIDefinition the swagger-maven-plugin will produce a NullPointerException

This is because OpenAPISorter will try to create a TreeMap with null.

Stacktrace:

Caused by: java.lang.NullPointerException
    at java.util.TreeMap.putAll (TreeMap.java:313)
    at java.util.TreeMap.<init> (TreeMap.java:185)
    at io.openapitools.swagger.OpenAPISorter.sortPaths (OpenAPISorter.java:50)
    at io.openapitools.swagger.OpenAPISorter.sort (OpenAPISorter.java:41)
    at io.openapitools.swagger.GenerateMojo.execute (GenerateMojo.java:127)

When at least one webservice is present the build succeeds.

Ability to use wildcards in resourcePackages

Hi, thanks for this excellent plugin! I've tried using wildcards in the resourcePackages tag, is that supported? I seem to get null pointers no matter what I try. Note it works perfectly when I specify the exact package(s). Currently I use holon to generate swagger.yaml but it only does that when the app is up and running, and since my apps are behind an API gateway I have to briefly expose the app publicly during the jenkins build in order to get the yaml to feed the gateway, which is a security risk for me. So this is the perfect solution for me! However, populating the gateway is framework code and in my opinion something that the developers should not need to be concerned with, so ideally if they add a new REST API class, the services would just appear in the gateway during the next build without them having to configure additional packages in the build section of the pom. And the only solution I can see for that is allowing wildcards in the resources declaration:

    <resourcePackages>
      <resourcePackage>edu.upenn.isc.*</resourcePackage>
    </resourcePackages>

Please let me know if this would be possible and if you would be interested, I could attempt to contribute code if needed.

Best,
Charles Harvey

Problem at generation of security scheme

Describe the bug
I want to add A SecurityRequirement to my Open API docs.

After interpreting https://github.com/openapi-tools/swagger-maven-plugin/blob/master/src/main/java/io/openapitools/swagger/config/SwaggerSecurityRequirement.java , this is what I did:

<components>
	<securitySchemes>
		<authorization>
			<type>apiKey</type>
			<name>Authorization</name>
			<in>header</in>
			<scheme>http</scheme>
		</authorization>
		<area>
			<type>apiKey</type>
			<name>Area</name>
			<in>header</in>
			<scheme>http</scheme>
		</area>
	</securitySchemes>
</components>
<securityRequirements>
	<authorization>
		<entries>
			<name>Authorization</name>
		</entries>
	</authorization>
	<area>
		<entries>
			<name>Area</name>
		</entries>
	</area>
</securityRequirements>

This produces the following error:

[ERROR] Failed to execute goal io.openapitools.swagger:swagger-maven-plugin:2.1.5:generate (default) on project application-webservices:
Unable to parse configuration of mojo io.openapitools.swagger:swagger-maven-plugin:2.1.5:generate for parameter name: 
Cannot find default setter in class io.openapitools.swagger.config.SwaggerSecurityRequirement$Entry -> [Help 1]

However, if I remove the <name> tags from inside the <entries>, the maven-plugin does not throw any error.
But looking at the generated file, this is what was generated:

"security" : [ null, null ]

Expected behavior
The expected result would be :

  "security" : [ {"Authorization": []}, {"Area": []}],

Note: the securitySchemes tag is being created correctly. But to enable the schemes globally, the additional security tag is needed.

So this seems to be a bug while parsing the configuration. Or is there just a mistake in my configuration?

Bump swagger-core for enum fix

Would much appreciate if swagger-core could be updatetd to 2.1.3 or later, as it fixes an important regression in how enum values are inspected
(Support for overriding enum values with @JsonProperty or @JsonValue (#3553))

Add pretty-print option to JSON generation

It would be nice to have an option to generate a "pretty-printed" JSON schema. The current JSON schema is nicely compact but it's unreadable by humans.

It should be straightforward to add the option and the SerializationFeature.INDENT_OUTPUT configuration to the Jackson mapper.

V1.0.2 does not find any of my jaxrs classes

V1.0.2 does not work or maybe does not work with maven 3?
It does not find any of my classes for further processing the jaxrs annotations.
After I copied createClassLoader() from GenerateMojo from V2.0.1 over and the related init process the plugin works as expected.
I think there might be still reasons out there to use the Swagger Spec 2.0 for some people so it would be helpful to keep the V1.x alive. And the fix is so small - once the issue is found ;-)

Allow ObjectMapperProcessor to customise JSON mapping

Is your feature request related to a problem? Please describe.
I need to use an ObjectMapperProcessor to customise JSON mappings (to support Scala's Option type, among other things), but the schemas generated by io.openapitools.swagger:swagger-maven-plugin don't reflect the mappings configured by the ObjectMapperProcessor because there is no way to tell the plugin about my ObjectMapperProcessor.

Describe the solution you'd like
Please add an option to specify the classname of the ObjectMapperProcessor implementation, which would affect the schema generation so that it matches the runtime behaviour when the ObjectMapperProcessor is installed.

Describe alternatives you've considered
I tried switching to io.swagger.core.v3:swagger-maven-plugin because it has a configuration option objectMapperProcessorClass, but it doesn't seem to work as expected: swagger-api/swagger-core#3247

Additional context
Swagger's objectMapperProcessorClass configuration option is documented here:
https://github.com/swagger-api/swagger-core/wiki/Swagger-2.X---Integration-and-Configuration#configuration-properties

Incompatibility with Maven 3.3.9

We are using this plugin to generate a Swagger definition file in one of our projects. Once we wanted to deploy our artifacts to Nexus we ran into an issue on Jenkins (Maven version 3.3.9): https://gist.github.com/user667/c750fad5eb40956713b2c6ec366e1026
This is due to an incompatiblilty of Maven 3.3.9 and the dependencies set in this plugin, namely org.apache.maven.plugin-tools:maven-plugin-annotations:3.5 and org.apache.maven:maven-plugin-api:3.6.0, org.apache.maven:maven-core:3.6.0 and org.apache.maven:maven-artifact:3.6.0. Using Maven version 3.5+ doesn't have the issue.

Is it safe to use the workaround mentioned below (i.e. downgroading version 3.2.5/3.4)? And/or is it necessary to use the latest maven versions as a dependency?

To Reproduce
Use Maven (version 3.3.9) and deploy (mvn clean deploy) an artifact that uses this plugin.

Expected behavior
maven-deploy-plugin:3.0.0-M1:deploy should be successful.

Additional context
As a workaround, one can override the above dependencies:

<build>
    <pluginManagement>
        <plugins>
            <!-- See: https://github.com/openapi-tools/swagger-maven-plugin -->
            <plugin>
                <groupId>io.openapitools.swagger</groupId>
                <artifactId>swagger-maven-plugin</artifactId>
                <version>2.1.1</version>
                <!-- We need to downgrade certain Maven dependencies of this plugin in order to have successful builds on Jenkins (deploy) -->
                <dependencies>
                    <dependency>
                        <groupId>org.apache.maven</groupId>
                        <artifactId>maven-plugin-api</artifactId>
                        <version>3.2.5</version>
                    </dependency>
                    <dependency>
                        <groupId>org.apache.maven</groupId>
                        <artifactId>maven-core</artifactId>
                        <version>3.2.5</version>
                    </dependency>
                    <dependency>
                        <groupId>org.apache.maven</groupId>
                        <artifactId>maven-artifact</artifactId>
                        <version>3.2.5</version>
                    </dependency>
                    <dependency>
                        <groupId>org.apache.maven.plugin-tools</groupId>
                        <artifactId>maven-plugin-annotations</artifactId>
                        <version>3.4</version>
                    </dependency>
                </dependencies>
            </plugin>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-plugin-plugin</artifactId>
                <version>3.5.2</version>
            </plugin>
        </plugins>
    </pluginManagement>
</build>

OpenApi.json / yaml are not the same as one available during runtime

Describe the bug
generated json|yaml file has different content than one available on host:8080/openapi

To Reproduce

1. execute: $ mvn io.openapitools.swagger:swagger-maven-plugin:2.1.4:generate
2. start application and send request like: curl <host>:8080/openapi > runtime_openapi.yaml
3. compare the files with diff <generated>-openapi.yaml runtime_openapi.yaml

<       operationId: getAll
29,30c10,11
<         default:
<           description: default response
---
>         "200":
>           description: OK
34,37c15
<                 uniqueItems: true
<                 type: array
<                 items:
<                   $ref: '#/components/schemas/Fruit'
---
>                 $ref: '#/components/schemas/SetFruit'
39d16
<       operationId: add
46,47c23,24
<         default:
<           description: default response
---
74d43
<       operationId: hello
76,77c45,46
<         default:
<           description: default response
---
>         "200":
>           description: OK
84,89c53,58
<       operationId: greeting
<       requestBody:
<         content:
<           '*/*':
<             schema:
<               type: string
---
>       parameters:
>       - name: name
>         in: path
>         required: true
>         schema:
>           type: string
91,92c60,61
<         default:
<           description: default response
---
>         "200":
>           description: OK

Expected behavior
Both generated and runtime available openapi spec have the same content

Allow to set Swagger scanner class

In Swagger JAX-RS configuration, it is possible to set which type of resource scanner should be used to scan resources by specifying the "scannerClass" parameter of openapi-configuration. Either one of pre-defined ones can be used, or one can implement its own custom scanner implementing the OpenApiScanner interface.

The difference in the generated OpenAPI specification can be seen e.g. by using the sample project: swagger-maven-plugin-sample-project-scanner.zip. The project uses io.swagger.v3.jaxrs2.integration.JaxrsApplicationScanner, and so the generated OpenAPI specification contains only the resources defined by the RestApplication class; the plugin scans all @Path annotated endpoints, and thus produces different specification.

Do you think it would be a useful feature of the plugin to support?

Supporting API generation from Webflux Functional Endpoint

Hi, I am using springdoc-openapi-webflux-ui to generate documentation from functional endpoints in my reactive application. The generated document is only available on runtime (when app is running). I want to generate document in compile phase and wanted to use this plugin but its unable to detects apis. Can we add support for it?

A sample route function from the demo

	@Bean
	RouterFunction<ServerResponse> routerFunction() {
		return SpringdocRouteBuilder.route().GET("/coffees", this::all, ops -> ops.beanClass(CoffeeService.class).beanMethod("getAllCoffees")).build()
				.and(route().GET("/coffees/{id}", this::byId, ops -> ops.beanClass(CoffeeService.class).beanMethod("getCoffeeById")).build())
				.and(route().GET("/coffees/{id}/orders", this::orders, ops -> ops.beanClass(CoffeeService.class).beanMethod("getOrdersForCoffeeById")).build());
	}

Semantic of recursive scanning

Your code currently does not check for "package." but rather "package" with a startsWith, so if I have two packages like
a.b.cde.SomeWS
and
a.b.cdefgh.SomeWS

you'll match both classes if I specify a.b.cde as package and recurse flag is specified. That's why my code had a startsWith(package+".") in the check...

Hope you fix it...

Originally posted by @sunnymoon in #20 (comment)

Allow definition on "security" or enable inclusion of parent openapi definition

Is your feature request related to a problem? Please describe.
My API definition should contain reference to the used API key like

security:
- ApiKeyAuth: []

...

  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      name: X-API-KEY
      in: header

This seems not to be possible with the current plugin.

Describe the solution you'd like
Possible solutions - I like both ;-)

• enable usage of an appendable openapi definition which could contain this definition
• enable definition of securitySchemes and security in pom.xml

Examples containing date-time strings are not quoted in YAML output

Describe the bug
When I create a io.swagger.v3.oas.annotations.media.Content example with a date-time property, such as

Content(
    mediaType = MediaType.APPLICATION_JSON,
    examples = [ExampleObject(value = """{"refreshAt": "2022-03-03T12:12:16Z"}""")],
    schema = Schema(implementation = KeyUpdateCommandsResponse::class),
)

the plugin generates the following yaml output:

content:
  application/json:
    example:
      refreshAt: 2022-03-03T12:12:16Z

note that the refreshAt property is not escaped with quotation marks.

When I copy the generated yaml into the Swagger Editor, the example is rendered as:

"refreshAt": OrderedMap {}

which is incorrect.

The generated json format has the correct behaviour (but then again, it puts everything in double quotes, so to be expected).

To Reproduce
See above.

Expected behavior
the plugin generates the following yaml:

content:
  application/json:
    example:
      refreshAt: "2022-03-03T12:12:16Z"

Supporting multiple apiSources

Kongchen maven plugin supports generation of multiple api sources:
https://github.com/kongchen/swagger-maven-plugin#configuration-for-configuration

I don't see this option in io.openapitools.swagger.config.SwaggerConfig. Is it possible?

Add support for Spring REST annotations

The plugin that this plugin is based on (https://github.com/kongchen/swagger-maven-plugin) supports both JAX-RS and Spring annotations. It seems this plugin currently only supports JAX-RS. Are there any plans to add support for Spring annotations (@RestController, @RequestMapping, @GetMapping, @PostMapping, etc.) to this plugin? Or do you know of another project that supports Spring annotations and OpenAPI v3?

Add support for static HTML page generation with input from Handlebars template

Is your feature request related to a problem? Please describe.
I am able to generate the Swagger specification file in JSON and YAML, but I need to generate a static HTML document from the specification that can be hosted separately.

Describe the solution you'd like
It would be comfortable to have a configuration that would let us enable the generation of a static HTML while using a handlebars template. Also, a nested config that will have a default name for the generated html file, but can also be customized as per requirement.

Describe alternatives you've considered
I'm not aware of alternative that I can use. Any suggestion is welcome that can solve the problem.

Additional context
The feature is provided by Swagger plugin from Yukai Kong but it doesn't seem to be working with Swagger v3 annotations. It takes a Handlebars template to generate the static html document.

implement a skip flag

It would be nice if this plugin had a skip flag that could be used to skip generation, like most maven plugins support.