DEV Community

Martin Hauner
Martin Hauner

Posted on • Edited on • Originally published at hauner.github.io

openapi-processor-spring

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 or HandlerMethodArgumentResolver) to controller endpoints without adding it to the OpenAPI description

  • providing 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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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'
}
Enter fullscreen mode Exit fullscreen mode
  • 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 gradle dependencies block and tells the plugin which processor to use. The plugin will create a processSpring task to run the given processor.
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"
    }

}
Enter fullscreen mode Exit fullscreen mode
  • last step is to include the generated files into the build. With standard gradle configurations we add the targetDir to the java source set so that gradle will compile them. To automatically re-generate the api when necessary we add the processSpring task as a dependency to the compileJava task.
sourceSets {
    main {
        java {
            srcDir "${projectDir}/build/openapi"
        }
    }
}

compileJava.dependsOn ('processSpring')
Enter fullscreen mode Exit fullscreen mode

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)

Collapse
 
tobiashochguertel profile image
Tobias Hochgürtel

wvag is the difference between this generator and the openapi-codegen (Swagger Geneator..)?

Collapse
 
hauner profile image
Martin Hauner

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.