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.
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>
To generate multiple clients, specify multiple <execution>
sections.
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.
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') |
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') |
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. |