Principled code generation from OpenAPI specifications

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