swagger-tools
Overview
This project provides a set of tools to generate java code from API definition.
Source
- Swagger 2.0 or OpenAPI 3.0 API definition in json/yaml format
- Extensions
- x-ignore to exclude operations from the code generation process
- x-ignore-server to exclude operations from the server code generation process
- x-ignore-server-client to exclude operations from the client code generation process
- x-name to specify OpenAPI 3 requestBody parameter name
- x-base-path to specify OpenAPI 3 API base path
- x-response-entity to make Client/Server return Spring ResponseEntity object
- x-model-package to specify package name for the model classes
Targets
- Model classes. Supported dialects:
- Jackson2
- Java client SDK, can be used for unit testing or to create java client applications. Supported dialects:
- Spring RestTemplate
- Spring WebClient
- Apache HttpClient
- Server API interfaces with HTTP mapping annotations. Supported dialects:
- Spring WebMVC
- Spring Webflux
- JAX-RS
Run from command line
To get list of arguments:
java -jar swagger-tools-cli.jar
To generate models and client code:
java -jar swagger-tools-cli.jar \
--source.location=swagger.yaml \
--target.model.location=./generated \
--target.model.model-package=com.example.model \
--target.client.location=./generated \
--target.client.model-package=com.example.model \
--target.client.client-package=com.example.client \
Run from maven
<build>
<plugins>
<plugin>
<groupId>com.github.agliznetsov.swagger-tools</groupId>
<artifactId>swagger-tools-maven-plugin</artifactId>
<version>0.2.0</version>
<executions>
<execution>
<id>petstore</id>
<goals>
<goal>generate</goal>
</goals>
<configuration>
<sources>
<param>${project.basedir}/src/main/resources/petstore.yaml</param>
</sources>
<options>
<target.model.location>${project.build.directory}/generated-sources/swagger</target.model.location>
<target.model.model-package>org.swaggertools.demo.model</target.model.model-package>
<target.client.location>${project.build.directory}/generated-sources/swagger</target.client.location>
<target.client.model-package>org.swaggertools.demo.model</target.client.model-package>
<target.client.client-package>org.swaggertools.demo.client</target.client.client-package>
</options>
</configuration>
</execution>
</executions>
</plugin>
</plugins>
</build>
Plugin configuration parameters:
- skip: Skip code generation
- help: Print the list of options
- options: Key/Value map of arguments for the code generator. Same as for the commandline version.
Check also a complete sample application: demo-webmvc
Run from gradle
There is no specific gradle plugin yet, but you can run code generator from gradle using command line version:
configurations {
swagger
}
dependencies {
swagger 'com.github.agliznetsov.swagger-tools:swagger-tools-cli:0.6.0'
}
task "swagger-generate"(type: JavaExec) {
classpath = configurations.swagger
main = 'org.swaggertools.cli.Generator'
args = [
"--source.location", "src/main/resources/swagger.yaml",
"--target.model.location", "src/main/java",
"--target.model.model-package", "com.example.model",
]
}
Extensions
Additional targets can be added via java ServiceLoader:
- Implement Target interface
- List it in the META-INF/services
- Add your jar file to the classpath of the CLI or maven plugin