It supports an approach where you explicitly define and document your Service API (using OpenAPI) with the Interface to the outside and its usage in mind before you implement it. You do not derive the API later from the implementation and its implicit design. (of course, adapt as you go…)
The advantages are:
you have a single place to maintain the api which makes it easier to create a consistent api and keep the overview.
it is easy to document in plain text. You can use markdown in the OpenAPI
The processor generates java interfaces based on the endpoint description of the API and simple POJO classes for parameter or response objects defined in the API. The processor adds all the required spring & jackson annotations to the interface and all that is left to you is the implementation of the generated interfaces in any way you like.
The interfaces will help to keep the implementation in sync with the API. If anything relevant changes in the API the interface changes and the compiler will warn that the interface is not implemented correctly.
The target programming language is Java so the generated code is usable from most JVM languages.
See the processor intro for a short example.
openapi-processor has a playground application. You can try out some samples, or your own yaml and view the code that the processor generates.
generates only java interfaces and java model classes (get/set POJOs) for all defined endpoints and schemas to allow full control of the endpoint implementation. It does not generate any other file. See processor.
powerful type mappings with generic support (one level) to map schemas defined in the openapi.yaml to existing java types.
For example to map the openapi
arraytype to a different java collections or to map paging parameters and results to th Spring types like
mappings can be defined globally or for a specific response or parameter or even only for a specific endpoint. See type mapping.
Annotation based WebFlux support. Actually there is no explicit WebFlux support, but the mapping allows defining a single, and a multi wrapper class. single wraps non-array like result types (e.g.
Mono<>). multi replaces array like result types or parameters with the given multi mapping. For example, it will replace
Flux<String>if the multi mapping contains the fully qualified
generates human readable code.
add additional parameters to an endpoint which are not defined in the OpenAPI description. For example to pass a
HttpServletRequestto the endpoint implementation.
supports bean validations. The constraints of the openapi description map to java bean validation annotations.
allows excluding endpoints from generation. This is useful if the processor does not create the correct code for an endpoint. That way the processor can still be used for all the other endpoints.
handle multiple responses by generating one endpoint method for each response content type.
the generated code does not use swagger annotations. There is no need to generate the documentation from the code when the code originates from the documentation (i.e. an openapi.yaml).
maven & gradle support The plugin docs show how to run a processor and how to add the generated sources to the build.
See the release notes to find the latest release. The full artifact name is:
In case some feature is missing, or the generated code is not 100% what you would expect create an issue. Preferably with a test case. Providing a test case will help significantly :-)
A test case is a single folder with two subfolders containing the source files, and the expected output files:
my-test-case +--- inputs.yaml |--- inputs | +--- mapping.yaml | \--- openapi.yaml +--- generated.yaml \--- generated +--- api | \--- EndpointApi.java \--- model \--- Foo.java
generated.yaml use the same simple format:
items: - inputs/openapi.yaml - inputs/mapping.yaml
items: - generated/api/EndpointApi.java - generated/model/Foo.java
See the existing integration tests for some examples.