Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/guardrail-dev/guardrail-maven-plugin
Principled code generation from OpenAPI specifications
https://github.com/guardrail-dev/guardrail-maven-plugin
codegen guardrail maven-plugin openapi swagger
Last synced: 4 days ago
JSON representation
Principled code generation from OpenAPI specifications
- Host: GitHub
- URL: https://github.com/guardrail-dev/guardrail-maven-plugin
- Owner: guardrail-dev
- License: mit
- Created: 2018-04-05T20:54:27.000Z (over 6 years ago)
- Default Branch: master
- Last Pushed: 2024-05-05T14:23:22.000Z (6 months ago)
- Last Synced: 2024-05-07T18:27:52.280Z (6 months ago)
- Topics: codegen, guardrail, maven-plugin, openapi, swagger
- Language: Scala
- Homepage: https://guardrail.dev
- Size: 308 KB
- Stars: 2
- Watchers: 11
- Forks: 6
- Open Issues: 16
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
guardrail-maven-plugin
======================
A maven plugin for adding clients and servers generated by [guardrail](https://github.com/guardrail-dev/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`:
```xml
...
dev.guardrail
guardrail-maven-plugin
Please use the latest available release!
dev.guardrail
guardrail-java-dropwizard_2.13
...
dev.guardrail
guardrail-java-async-http_2.13
...
generate-petstore-client
generate-sources
scala
${project.basedir}/src/main/swagger/example-client.yaml
com.example
example-client
1.2.3
com.example.client
generate-myservice-server
generate-sources
scala
${project.basedir}/src/main/swagger/my-service.yaml
com.example.server
publish-myservice-server
deploy-openapi-spec
${project.basedir}/src/main/swagger/my-service.yaml
com.example
my-service
...
```
## Configuration
To generate multiple clients, specify multiple `` 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 ``s that describe the set of functionality desired for an individual guardrail execution |
| customImports | A list of ``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. |