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.