logo

openapi-processor

openapi-processor is a small framework that converts an OpenAPI yaml description to a target format. Usually Java code. 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 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 description properties.

  • 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.

code generation
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.

process

supported target formats

openapi processor spring?color=009051&label=latest

creates Spring Boot java interfaces & models (pojos) from the OpenAPI description using spring annotations.

openapi processor micronaut?color=009051&label=latest

creates Micronaut java interfaces & models (pojos) from the OpenAPI description using micronaut annotations.

openapi processor json?color=009051&label=latest

converts the OpenAPI yaml description to json format.

supported build tools

openapi processor gradle?color=009051&include prereleases&label=latest

gradle plugin to run any processor from Gradle.

openapi processor maven plugin?color=009051&label=latest

maven plugin to run any processor from Maven.

.. 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.