guardrail-maven-plugin

A maven plugin for adding clients and servers generated by guardrail to your service.

This plugin also supports publishing OpenAPI spec files to a maven server, and also consuming files via maven rather than through a local file.

Usage

Add to your pom.xml:

<build>
  <plugins>
    ...
    <plugin>
      <groupId>dev.guardrail</groupId>
      <artifactId>guardrail-maven-plugin</artifactId>
      <version>Please use the latest available release!</version>
      <dependencies>
        <!-- List the guardrail modules you wish to use. For more, see the module lists here: https://guardrail.dev/ -->
        <dependency>
          <groupId>dev.guardrail</groupId>
          <artifactId>guardrail-java-dropwizard_2.13</artifactId>  <!-- SpringMVC also available! -->
          <version>...</version>
        </dependency>
        <dependency>
          <groupId>dev.guardrail</groupId>
          <artifactId>guardrail-java-async-http_2.13</artifactId>
          <version>...</version>
        </dependency>
      </dependencies>
      <executions>
        <!-- This execution generates an API client from an OpenAPI spec file -->
        <execution>
          <id>generate-petstore-client</id>
          <goals>
            <goal>generate-sources</goal>
          </goals>
          <configuration>
            <language>scala</language>
            <!-- Generate from a local spec file -->
            <specPath>${project.basedir}/src/main/swagger/example-client.yaml</specPath>
            <!-- Or, generate from a spec file stored in a maven repository -->
            <specArtifact>
                <groupId>com.example</groupId>
                <artifactId>example-client</artifactId>
                <version>1.2.3</version>
            </specArtifact>
            <packageName>com.example.client</packageName>
          </configuration>
        </execution>
        <!-- This execution generates server resources/routes from an OpenAPI spec file -->
        <execution>
          <id>generate-myservice-server</id>
          <goals>
            <goal>generate-sources</goal>
          </goals>
          <configuration>
            <language>scala</language>
            <specPath>${project.basedir}/src/main/swagger/my-service.yaml</specPath>
            <packageName>com.example.server</packageName>
          </configuration>
        </execution>
        <!-- This execution publishes the server spec file to the maven server specified in <distributionManagement> -->
        <execution>
          <id>publish-myservice-server</id>
          <goals>
            <goal>deploy-openapi-spec</goal>
          </goals>
          <configuration>
            <specPath>${project.basedir}/src/main/swagger/my-service.yaml</specPath>
            <groupId>com.example</groupId>
            <artifactId>my-service</artifactId>
          </configuration>
        </execution>
      </executions>
    </plugin>
    ...
  </plugins>
</build>

Configuration

To generate multiple clients, specify multiple <execution> sections.

Code Generation

Parameter Name	Description
outputPath	Location of generated classes (defaults to ${project.build.directory}/generated-sources/swagger-clients)
language	Which language to generate (defaults to scala currently, will change to java in the future. Valid values are: java, scala)
kind	What kind of code should be generated (defaults to client. Valid values are: client, server, models)
specPath	Location of the swagger specification file
specArtifact	Sub-object used to specify the location of the swagger specification in a maven repository (see below)
packageName	Package name to use for the generated classes
dtoPackage	Package name for the data transfer objects (defaults to same as packageName)
tracing	Whether or not to generate clients that accept a TracingContext which will send tracing headers to the remote service (defaults to false)
modules	A list of <module>s that describe the set of functionality desired for an individual guardrail execution
customImports	A list of <customImport>s that will be added to the top of all generated files. Useful for providing additional typeclass instances or domain-specific types
framework	The framework to generate the code for (defaults to akka-http)

Only one of specPath or specArtifact should be provided; if both are provided, specPath will be used.

specArtifact

The specArtifact parameter is a sub-object that contains the following parameters:

Parameter Name	Description
groupId	Maven group ID of the published artifact (defaults to project's groupID)
artifactId	Maven artifact ID of the published artifact
version	Version of the published artifact
extension	File extension of the published artifact (default is to try, in order: 'yaml', 'yml', 'json')
type	Maven artifact type of the published artifact (defaults to 'openapi-spec')
classifier	Maven artifact classifier of the published artifact (defaults to 'openapi-spec')

Spec Publishing

Parameter Name	Description
specPath	Location of the swagger specification file
groupId	Maven group ID used when publishing (defaults to the project POM group ID)
artifactId	Maven artifact ID used when publishing (defaults to the project POM artifact ID)
type	Maven artifact type used when publishing (defaults to 'openapi-spec')
classifier	Maven artifact classifier used when publishing (defaults to 'openapi-spec')

General

The plugin also interprets a single system property:

Property	Description
guardrail.loglevel	Changes Guardrail's log level. Possible options are "debug", "info", "warning" (the default), "error", and "silent".
guardrail.codegen.skip	When set to true, skips generating code.
guardrail.deploy.skip	When set to true, skips deploying the OpenAPI spec file.