openapi-processor-spring (or short: oap-spring) is an OpenAPI interface & model Java code generator for Spring Boot.
It is generating code for annotation based (MVC) controllers (oap-spring has experimental support for Mono<>
and Flux<>
like wrappers that makes it possible to use WebFlux with annotations).
Its goal is to provide a smooth & straight forward mapping from an OpenAPI yaml description to Spring Boot Java code:
allowing common Spring Boot code patterns, like passing additional parameters (for example
HttpServletRequest
orHandlerMethodArgumentResolver
) to controller endpoints without adding it to the OpenAPI descriptionproviding an easy mapping to existing Java types with (simple) generic support
getting out of the way if the processor does not create the expected code for single endpoints.
You will need a gradle based spring boot project and the oap-gradle plugin to use oap-spring.
See the quick overview below for how it works or check the following links:
Current 1.0 milestone releases are:
com.github.hauner.openapi:openapi-processor-spring:1.0.0.M14
com.github.hauner.openapi:openapi-processor-gradle:1.0.0.M7
usage overview
Here is a quick usage overview. A more detailed description is available in the documentation.
api & processor configuration
First, we put an openapi.yaml
with our OpenAPI description in the src/api
folder of our project. We put another yaml file mapping.yaml
into the same place. This is the configuration of the processor.
/src/api/
openapi.yaml
mapping.yaml
the minimum content of the mapping.yaml
is the target package name for the code the processor generates. It will create two sub-packages api
and model
for the endpoint interfaces and the model classes.
options:
package-name: com.github.hauner.openapi
gradle configuration
To enable the processor we add the following snippets to the build.gradle
:
- add the oap-gradle plugin
plugins {
id 'com.github.hauner.openapi-processor' version '1.0.0.M7'
}
- next is the plugin configuration for oap-spring.
apiPath
,mapping
&targetDir
configure the paths of the input files, and the processor configuration file.processor
is like a dependency in the standard gradledependencies
block and tells the plugin which processor to use. The plugin will create aprocessSpring
task to run the givenprocessor
.
openapiProcessor {
apiPath "${projectDir}/src/api/openapi.yaml"
spring {
processor 'com.github.hauner.openapi:openapi-processor-spring:1.0.0.M14'
mapping "${projectDir}/src/api/mapping.yaml"
targetDir "${projectDir}/build/openapi"
}
}
- last step is to include the generated files into the build. With standard gradle configurations we add the
targetDir
to thejava
source set so that gradle will compile them. To automatically re-generate the api when necessary we add theprocessSpring
task as a dependency to thecompileJava
task.
sourceSets {
main {
java {
srcDir "${projectDir}/build/openapi"
}
}
}
compileJava.dependsOn ('processSpring')
Now when we change openapi.yaml
or mapping.yaml
gradle automatically runs the processor to update the api code before it is compiling the rest of our code.
That's it.
Top comments (2)
wvag is the difference between this generator and the openapi-codegen (Swagger Geneator..)?
The motivation of openapi-processor is to have a less complex tool that is easier to use and that has better support for some Spring features and generates simpler code.
Less complexity means: it does only create plain Java interfaces and simple model classes and it does not have a lot of options.