openapi-processor is a small framework that converts an OpenAPI yaml description to a target format.
The primary target is Java code. It generates interfaces and pojos based on the API and you implement the interfaces in your controllers.
The target programming language is Java, which makes the generated code usable from most JVM languages.
starting with an API
openapi-processor is useful if 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, this is not a one time step but an iterative process.
The disadvantages are:
you have to learn OpenAPI & write the OpenAPI description.
the code generation has its limits and does not support all use cases.
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.
you don’t need to manually write the controller annotations and remember all the annotation details.
you can easily skip generation of endpoints that have special (unsupported) requirements and write them manually.
it is easy to document in plain text. You can use markdown in the OpenAPI
it helps to keep the implementation in sync with the OpenAPI description. If anything relevant changes in the API the interface changes and the compiler will warn that the interface is not implemented correctly.
A processor generates java interfaces based on the endpoint descriptions of the API and simple POJO classes for parameter or response schemas defined in the API with the help of the type mapping configuration. The processor adds all the required annotations to the interface and all that is left to you is the implementation of the generated interfaces in any way you like.
supported target formats
converts the OpenAPI yaml description to json format.
supported build tools
.. a few things it can do
it generates java interfaces and java model (pojo) classes only for all defined endpoints and schemas to allow full control of the endpoint implementation. It does not generate any other file.
it has a powerful type mapping configuration (one level generic support) to map schemas defined in the OpenAPI description to existing java types. Mappings can be defined globally, for a specific response, parameter or endpoint or http method (of an endpoint).
it can add additional parameters to an endpoint which are not defined in the OpenAPI description. For example to pass an
HttpServletRequest to the endpoint implementation which is nothing you want to describe in the API.
it generates human-readable code.
it supports bean validations. The constraints of the openapi description map to java bean validation annotations.
it supports json merge patch apis by generating pojos with jackson-databind-nullable where requested.
it allows to exclude 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.
it handles multiple responses by generating one endpoint method for each response content type.
it handles relative
$ref 's between multiple yaml files.