DEV Community: Martin Hauner

mapping OpenAPI formats

Martin Hauner — Thu, 08 Jun 2023 10:00:00 +0000

what is openapi-processor? openapi-processor is an easy-to-use tool to generate java based (annotated) controller interfaces and pojos (model classes) from an OpenAPI yaml description. It supports Spring Boot, Micronaut with maven or gradle.

Assume we have this simple (but useless ;-) OpenAPI description. It uses a custom integer format to specify that the integer parameter and response represents a year.

openapi: 3.1
info:
  title: pending API
  version: 1.0.0

paths:
  /query:
    get:
      description: echo query parameter with type mapping
      parameters:
        - name: year
          description: the year
          in: query
          required: true
          schema:
            type: integer  # <1>
            format: year
      responses:
        '200':
          description: echo response
          content:
            text/plain:
              schema:
                type: integer  # <1>
                format: year

<1> the integer type with custom format.

By default, openapi-processor-spring does not know what to do with the custom format and simply maps the OpenAPI integer to a Java Integer.

the generated interface code

package io.openapiprocessor.oap.api;

import io.openapiprocessor.oap.support.Generated;
import javax.validation.constraints.NotNull;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;

@Generated(value = "openapi-processor-spring", version = "2023.2")
public interface Api {

    /**
     * echo query parameter with type mapping
     *
     * @return echo response
     */
    @GetMapping(
            path = "/query",
            produces = {"text/plain"})
    Integer getQuery(@RequestParam(name = "year") @NotNull Integer year);

}

Since Java has a java.time.Year class it could be useful to use it instead of Integer.

We can easily help openapi-processor to generate the interface with java.time.Year by adding a type mapping to the mapping.yaml configuration.

mapping.yaml

openapi-processor-mapping: v3

options:
  generated-date: false
  package-name: io.openapiprocessor.oap
  bean-validation: javax
  javadoc: true

map:
  types:
    - type: integer:year => java.time.Year # <1>

<1> this is the interesting part of the mapping.yaml. It tells the processor to map the integer custom format to the java.time.Year class.

The left side of the arrow is the type : format combination used in the OpenAPI and on the right side is the fully qualified java class name that is used in the generated code.

Regenerating the code will now generate the interface like this:

the generated interface code

package io.openapiprocessor.oap.api;

import io.openapiprocessor.oap.support.Generated;
import java.time.Year;
import javax.validation.constraints.NotNull;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;

@Generated(value = "openapi-processor-spring", version = "2023.2")
public interface Api {

    /**
     * echo query parameter with type mapping
     *
     * @return echo response
     */
    @GetMapping(
            path = "/query",
            produces = {"text/plain"})
    Year getQuery(@RequestParam(name = "year") @NotNull Year year); // <1>

}

<1> it is now using java.time.Year instead of Integer.

Easy :-)

If such a custom type is used in a property of an OpenAPI schema, openapi-processor will use the same type mapping definition.

We can use this simple mechanism for many other types to improve the generated code, for example:

type mapping examples

  - type: string:uuid => java.util.UUID
  - type: string:date-time => java.time.Instant
  - type: string:offset-date-time => java.time.OffsetDateTime

I'm sure you can find more useful mappings. :-)

Thanks for reading!

summary

This short article described how easy it is to improve the openapi-processor generated code with a type mapping.

See the documentation for more.

annotation mapping & bean-validation

Martin Hauner — Sun, 16 Oct 2022 15:44:06 +0000

The openapi-processor-spring/micronaut release 2022.5 adds a new annotation type mapping feature. It provides the possibility to add additional annotations to generated interfaces & classes.

what is openapi-processor?

openapi-processor is a small framework to process OpenAPI yaml files. Currently, openapi-processor provides java code generation for Spring Boot & Micronaut.

It does support gradle and maven with plugins to convert OpenAPI yaml files to java (controller) interfaces & (payload) pojo classes as part of the build process.

It generates Java because the controller interface and pojo classes are easily usable from other jvm languages. Usually you will just use them without looking at the generated code.

annotation mapping

annotation type mapping allows to add annotations to a generated model class or to an endpoint method parameters of that class.

Let's look at a contrived example to add a custom bean validation to the pojo model class of a schema.

See annotation mapping documentation for more.

the example api

here is a simple api that takes a Foo schema as request body. The schema has some (useless ;-) number constraints on its properties.

openapi.yaml

openapi: 3.1.0
info:
  title: annotation mapping example
  version: 1.0.0

paths:
  /foo:
    post:
      summary: annotation mapping example endpoint.
      description: a simple endpoint where an annotation mapping is used on the request body
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Foo'
        required: true
      responses:
        '201':
          description: empty response

components:
  schemas:
    Foo:
      type: object
      properties:
        foo1:
          type: integer
          minimum: 0
        foo2:
          type: integer
          minimum: -10

bean validation annotations

Enabling bean validation in the mapping.yaml (the processor configuration) will generate a Foo class with bean validation annotations for the property constraints.

generated file

package io.openapiprocessor.openapi.model;

import com.fasterxml.jackson.annotation.JsonProperty;
import io.openapiprocessor.openapi.support.Generated;
import javax.validation.constraints.DecimalMin;

@Generated(value = "openapi-processor-spring", version = "2022.5")
public class Foo {

    @DecimalMin(value = "0") // <1>
    @JsonProperty("foo1")
    private Integer foo1;

    @DecimalMin(value = "-10") // <1>
    @JsonProperty("foo2")
    private Integer foo2;

    public Integer getFoo1() {
        return foo1;
    }

    public void setFoo1(Integer foo1) {
        this.foo1 = foo1;
    }

    public Integer getFoo2() {
        return foo2;
    }

    public void setFoo2(Integer foo2) {
        this.foo2 = foo2;
    }

}

<1> the bean validation annotations created from the OpenAPI constraints.

custom bean validation annotation

Now we like to add a validation that checks the sum of the two Integer properties by writing @Sum(24).

Let's create the annotation

manually created custom bean validation annotation

package io.openapiprocessor.samples.validations;


import javax.validation.Constraint;
import javax.validation.Payload;
import java.lang.annotation.*;

@Constraint (validatedBy = {FooSumValidator.class})
@Target ({ ElementType.TYPE, ElementType.PARAMETER })
@Retention (value = RetentionPolicy.RUNTIME)
public @interface Sum {
    String message () default "invalid sum";
    Class<?>[] groups () default {};
    Class<? extends Payload>[] payload () default {};

    int value();
}

and the validation code.

manually created validation

package io.openapiprocessor.samples.validations;

import io.openapiprocessor.openapi.model.Foo;

import javax.validation.ConstraintValidator;
import javax.validation.ConstraintValidatorContext;

public class FooSumValidator implements ConstraintValidator<Sum, Foo> {
    private Integer sum;

    @Override
    public void initialize (Sum constraintAnnotation) {
        sum = constraintAnnotation.value ();
    }

    @Override
    public boolean isValid (Foo value, ConstraintValidatorContext context) {
        return value.getFoo1 () + value.getFoo2 () == sum;
    }
}

mapping for the custom annotation

Now comes the interesting part, the annotation type mapping that tells the processor to add our custom annotation to the generated Foo pojo model class.

processor configuration mapping.yaml

openapi-processor-mapping: v2.1 # <1>

options:
  package-name: io.openapiprocessor.openapi
  bean-validation: true

map:
  types:
    # <2>
    - type: Foo @ io.openapiprocessor.samples.validations.Sum(24)

<1> the new mapping version. Using another version will produce a warning that the mapping is invalid.

<2> the annotation mapping that tells the processor to @nnotate the Foo schema (Foo is the name of the OpenAPI schema) with the given annotation to the pojo model class generated for the Foo schema. The annotation is given with the fully qualified name (required to create the import) and (optionally) with fixed parameters.

model class with custom annotation

Now, with the annotation mapping in the configuration the processor will generate Foo like this:

generated file with custom annotation

package io.openapiprocessor.openapi.model;

import com.fasterxml.jackson.annotation.JsonProperty;
import io.openapiprocessor.openapi.support.Generated;
import javax.validation.constraints.DecimalMin;
import io.openapiprocessor.samples.validations.Sum;

@Sum(24) // <1>
@Generated(value = "openapi-processor-spring", version = "2022.5")
public class Foo {

    @DecimalMin(value = "0")
    @JsonProperty("foo1")
    private Integer foo1;

    @DecimalMin(value = "-10")
    @JsonProperty("foo2")
    private Integer foo2;

    public Integer getFoo1() {
        return foo1;
    }

    public void setFoo1(Integer foo1) {
        this.foo1 = foo1;
    }

    public Integer getFoo2() {
        return foo2;
    }

    public void setFoo2(Integer foo2) {
        this.foo2 = foo2;
    }

}

<1> our custom bean validation annotation.

summary

This little article described how to add a custom annotation to a generated class by adding an annotation type mapping to the processor mapping configuration.

To learn more about openapi-processor and how to generate controller interfaces and model classes from an OpenAPI description take a look at the documentation.

openapi-processor-spring 2021.4 & micronaut 2021.2

Martin Hauner — Mon, 31 May 2021 21:44:00 +0000

what is openapi-processor?

openapi-processor is a small framework to process OpenAPI yaml files. Currently, openapi-processor provides java code generation for Spring Boot, Micronaut and conversion to json.

It does support gradle and maven to run any openapi-processor as part of the build process.

See the documentation for more. There is also a playground to preview the processors.

what is new?

See the release notes for the full details (it is the same for spring & micronaut).

Apart from a couple of bug fixes and improvements for multipart requests and bean-validations, openapi-processor is now able to automatically add a suffix to the generated model classes.

This is enabled by configuring the model-name-suffix in the mapping.yaml:

openapi-processor-mapping: v2

options:
  package-name: io.openapiprocessor.sample
  model-name-suffix: Resource # or Dto or ...

The model-name-suffix option sets a suffix that is automatically appended to all generated model and enum classes.

The suffix helps to

avoid duplicate class names in generated code and normal code
makes it easier to recognize which role or in which context a class is used. Is it a data transfer class or is it a domain class?
keeps the suffix "noise" out of the OpenAPI description

Usually you will separate the classes by putting them in different packages. This helps to distinguish the classes, but when both are used in the same code, i.e. when converting one format to the other, it is a lot easier to distinguish them by their class name instead of their package name.

If a schema name from the OpenAPI description already ends with the model-name-suffix, the processor will not append the suffix. This allows to migrate an existing api with a suffix in the API to model-name-suffix step by step.
Example:

OpenAPI

paths:
  /foo:
    get:
      responses:
        '200':
          description: the foo result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Foo' # (1)

components:
  schemas:

    Foo:
      type: object
      properties:
        nested:
          $ref: '#/components/schemas/BarResource' # (1)

    BarResource:
      type: object
      properties:
        prop:
          type: string

mapping.yaml

openapi-processor-mapping: v2

options:
  package-name: io.openapiprocessor.sample
  model-name-suffix: Resource # (2)

Java

// interface
public interface Api {

    @Mapping("/foo")
    FooResource getFoo(); // (3)

}

// pojos
public class FooResource { // (3)

    // ...

    @JsonProperty("nested")
    private BarResource nested;

    // ...
}

public class BarResource { // (4)

    // ...
}

a schema name without suffix
the suffix configuration
the class name of the Foo schema got the configured Resource suffix
the class name of the BarResource is identical to the original schema name. Since the existing suffix is equal to model-name-suffix it is ignored. Otherwise, This prevents funny class names like BarResourceResource.

That’s it.

openapi-processor-spring type mapping

Martin Hauner — Fri, 14 Aug 2020 08:45:24 +0000

what is openapi-processor?

openapi-processor is a small framework to process OpenAPI yaml files. Currently, openapi-processor provides java code generation for Spring Boot and conversion to json.

It does support gradle and maven to run any openapi-processor as part of the build process.

See the documentation for more. There is also a playground to preview the processors.

openapi-processor-spring

openapi-processor-spring (oap-spring) generates server side Java code for Spring Boot from an OpenAPI description. It generates interfaces for the endpoints with all the required Spring annotations, and it generates model classes (simple POJOs) with Jackson annotations for the OpenAPI schemas used in those endpoints.

By creating a controller that implements a generated interface it gets easier to implement the expected endpoints. Spring will automatically pick up all annotations on the generated interface methods. You can concentrate on the implementation.

what is type mapping?

Code generation is tricky. It is impossible to generate the perfect code just from the OpenAPI description. There are many cases where the generator needs our help to generate the code we like.

Just think of collections. OpenAPI has a single schema abstraction to describe collections: the *array*. It does not need more.

Using array (e.g. String[]) in Java is possible (and that is what oap-spring is using by default) but usually we prefer a more powerful and easier to use collection like List or Set etc.

That is why we need type mapping. Type mapping allows us to map an OpenAPI schema to a specific Java class.

The generator does use the mapping to replace any occurrence of the given OpenAPI schema in the generated code with the mapped target Java type. It doesn't matter if it is a parameter, response or a property of an object schema.

If an OpenAPI model schema (which would normally generate a POJO class) gets mapped to an existing Java class oap-spring will not generate a (duplicate) POJO class.

where to specify type mappings?

Type mapping is part of the openapi-processor yaml configuration file mapping.yaml. It should be a sibling of the OpenAPI yaml files (i.e. in the same directory).

The file looks like this:

openapi-processor-mapping: v2 # <1>

options:
  package-name: io.openapiprocessor.mapping # <2>

map:
   # java type mappings # <3>

<1> sets the configuration file format. It must be present with version 2 to use the mapping format described below.

<2> sets the Java package for the generated source files.

<3> map is the parent key of all type mappings.

how to specify a type mapping?

Type mapping uses a simple notation to specify a mapping:

{collection}:  # <1>
  {key}: {source type} => {target type} # <2>

<1> this defines the mapping collection. All mappings are grouped into a couple of fixed collections: types, parameters, responses and paths. A mapping collection can have any number of mappings.

<2> key defines what kind of mapping gets defined. For example type is the key for a global type mapping in the types collection. The value of the key maps a source type to a destination type by using an \=> arrow as the mapping operator. {source type} is the name of an OpenAPI type and {target type} is the fully qualified Java class name. Fully qualified because the processor needs the package name to generate an import statement for the target type.

Let's take a look at a few mapping examples. This is just an introduction and doesn't describe all the possibilities. See the type mapping documentation for more.

type mapping examples

global mapping

The first mapping is the global type mapping. Remembering the array example from above we can change it globally to java.util.Collection:

map:
  types: # <1>
    - type: array => java.util.Collection # <2>
    - type: Foo => io.openapiprocessor.samples.Foo # <3>

<1> types is the list of global type mappings. It is global because it is a direct child of the map key.
<2> - type is an actual mapping item, and it says: map the OpenAPI array schema type to Java's java.util.Collection.

Important:
the processor assumes that the Java target of array has a single generic parameter, and it will automatically use the array's item property type as the generic parameter.

<3> this one maps an OpenAPI schema Foo to an existing Java class in our code base.

path mapping

The second mapping is path-based type mapping and it is quite useful. It allows us to limit a mapping rule to a single endpoint. It is not used for any other endpoint.

Continue reading here.

Originally published at https://hauner.github.io on August 14, 2020.

configuring openapi-processor-maven

Martin Hauner — Mon, 27 Jul 2020 20:41:03 +0000

what is openapi-processor?

openapi-processor is a small framework to process OpenAPI yaml files. Currently, openapi-processor provides java code generation for Spring Boot and conversion to json.

It does support gradle and maven to run any openapi-processor as part of the build process.

See the documentation for more. There is also a playground to preview the processors.

The maven plugin is the newest member of the openapi-processor family, and the following sections provide a short introduction into its configuration.

introduction

I will just show the configuration of the maven plugin for integrating an OpenAPI yaml file. I don't describe the creation of a Spring Boot application.

Integrating it in a new Spring Boot starter project created by Spring Initializr (maven & web-mvc) should work without issues.

To see a working demo project take a look at the openapi-processor samples. The available samples have a pom.xml, and a build.gradle file, so you can build them using maven or gradle.

what to expect

Assuming a (simple) OpenAPI yaml file:

openapi: 3.0.2
    info:
      title: ping api
      version: 1.0.0

    paths:
      /ping:
        get:
          tags:
            - ping
          summary: returns a single "pong" string.
          description: super simple endpoint.
          responses:
            '200':
              description: pong
              content:
                text/plain:
                  schema:
                    type: string

the openapi-processor-maven plugin will generate a java interface by running the openapi-processor-spring (in short oap-spring).

The interface generated for the simple api will look like this (the package name io.openapiprocessor.simple is configurable):

package io.openapiprocessor.simple.api;

import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.GetMapping;

public interface PingApi {

    @GetMapping(path = "/ping", produces = {"text/plain"})
    String getPing();

}

You can now implement the interface to provide a working endpoint in your Spring Boot application.

The sample implements the interface with a hardcoded result like this:

package io.openapiprocessor.simple;

import  io.openapiprocessor.simple.api.PingApi;
import org.springframework.http.ResponseEntity;
import org.springframework.stereotype.Controller;

@RestController
public class PingController implements PingApi {

    @Override
    public String getPing () {
        return "pong";
    }

}

Now let's look at the necessary configuration to generate the interface from maven.

Continue reading here.

Originally published at https://hauner.github.io on July 18, 2020.

fixing a (transitive) dependency mess with gradle

Martin Hauner — Tue, 09 Jun 2020 09:02:18 +0000

the transitive dependency mess

While extracting openapi-processor-core from openapi-processor-spring I noticed duplicate dependencies with different and sometimes unexpected versions in the external libraries section o the project view (in IDEA).

In this case jackson packages.

Running gradle dependencies to see where they are coming from prints the following output (look for jackson):

gradle dependencies (simplified)

+--- com.fasterxml.jackson.module:jackson-module-kotlin:2.11.0
|    +--- com.fasterxml.jackson.core:jackson-databind:2.11.0 <1>
|    |    +--- com.fasterxml.jackson.core:jackson-annotations:2.11.0
|    |    \--- com.fasterxml.jackson.core:jackson-core:2.11.0
|    \--- com.fasterxml.jackson.core:jackson-annotations:2.11.0
+--- org.openapi4j:openapi-parser:1.0
|    \--- org.openapi4j:openapi-core:1.0
|         +--- com.fasterxml.jackson.core:jackson-databind:2.9.10 -> 2.11.0 (*) <2>
|         \--- com.fasterxml.jackson.dataformat:jackson-dataformat-yaml:2.9.10 -> 2.10.2 <3>
|              \--- com.fasterxml.jackson.core:jackson-core:2.10.2 -> 2.11.0 <4>
+--- io.swagger.parser.v3:swagger-parser:2.0.20
     +--- io.swagger.parser.v3:swagger-parser-v3:2.0.20
          +--- io.swagger.core.v3:swagger-models:2.1.2
          |    \--- com.fasterxml.jackson.core:jackson-annotations:2.10.1 -> 2.11.0 <5>
          +--- io.swagger.core.v3:swagger-core:2.1.2
          |    +--- com.fasterxml.jackson.core:jackson-annotations:2.10.1 -> 2.11.0
          |    +--- com.fasterxml.jackson.core:jackson-databind:2.10.1 -> 2.11.0 (*)
          |    +--- com.fasterxml.jackson.dataformat:jackson-dataformat-yaml:2.10.1 -> 2.10.2 (*) <6>
          |    +--- com.fasterxml.jackson.datatype:jackson-datatype-jsr310:2.10.1 <7>
          |         +--- com.fasterxml.jackson.core:jackson-annotations:2.10.1 -> 2.11.0
          |         +--- com.fasterxml.jackson.core:jackson-core:2.10.1 -> 2.11.0
          |         \--- com.fasterxml.jackson.core:jackson-databind:2.10.1 -> 2.11.0 (*)
          +--- com.fasterxml.jackson.core:jackson-annotations:2.10.2 -> 2.11.0
          +--- com.fasterxml.jackson.core:jackson-databind:2.10.2 -> 2.11.0 (*)
          \--- com.fasterxml.jackson.dataformat:jackson-dataformat-yaml:2.10.2 (*) <8>

There is a bit of a mess regarding the jackson packages and their versions. Here are a couple of entries:

<1> some with version 2.11.0
<2> upgrade from 2.9.10 to 2.11.0
<3> upgrade from 2.9.10 to 2.10.2
<4> upgrade from 2.10.2 to 2.11.0
<5> upgrade from 2.10.1 to 2.11.0
<6> upgrade from 2.10.1 to 2.10.2
<7> version 2.10.1
<8> version 2.10.2

The 3 top-level dependencies are direct dependencies (as gradle calls them) of my project and all of them use different jackson versions:

. com.fasterxml.jackson.module:jackson-module-kotlin:2.11.0
. org.openapi4j:openapi-parser:1.0
. io.swagger.parser.v3:swagger-parser:2.0.20

The first one is simple. Because com.fasterxml.jackson.module:jackson-module-kotlin is a jackson package itself, gradle selects 2.11.0 for the other transitive jackson dependencies.

jackson-module-kotlin (simplified)

    +--- com.fasterxml.jackson.module:jackson-module-kotlin:2.11.0
         +--- com.fasterxml.jackson.core:jackson-annotations:2.11.0
         +--- com.fasterxml.jackson.core:jackson-core:2.11.0
         \--- com.fasterxml.jackson.core:jackson-databind:2.11.0

Next one is org.openapi4j:openapi-parser:1.0. This one depends on jackson 2.9.10 and gradle upgrades everything to 2.11.0 because that is the newest version it found.

openapi-parser (simplified)

+--- org.openapi4j:openapi-parser:1.0
     +--- com.fasterxml.jackson.core:jackson-core:2.10.2 -> 2.11.0
     +--- com.fasterxml.jackson.core:jackson-databind:2.9.10 -> 2.11.0 (*)
     \--- com.fasterxml.jackson.dataformat:jackson-dataformat-yaml:2.9.10 -> 2.10.2

Ok, not for all jackson packages. It doesn't use 2.11.0 for jackson-dataformat-yaml.

It is not using 2.11.0 because gradle has not seen a newer version of jackson-dataformat-yamlthan 2.9.10. So why is it not 2.9.10? It is not because the third direct dependency io.swagger.parser.v3:swagger-parser:2.0.20 is using 2.10.1 and 2.10.2.

swagger-parser (simplified)

+--- io.swagger.parser.v3:swagger-parser:2.0.20
     +--- com.fasterxml.jackson.core:jackson-annotations:2.10.1 -> 2.11.0
     +--- com.fasterxml.jackson.core:jackson-core:2.10.1 -> 2.11.0
     +--- com.fasterxml.jackson.core:jackson-databind:2.10.1 -> 2.11.0
     +--- com.fasterxml.jackson.dataformat:jackson-dataformat-yaml:2.10.1 -> 2.10.2
     \--- com.fasterxml.jackson.datatype:jackson-datatype-jsr310:2.10.1

2.10.2 for jackson-dataformat-yaml. This is the highest version for this package so gradle picks it.

Gradle finally selects the following versions:

package (stripped com.fasterxml.jackson.)	version
`core:jackson-annotations`	2.11.0
`core:jackson-core`	2.11.0
`core:jackson-databind`	2.11.0
`dataformat:jackson-dataformat-yaml`	2.10.2 => want 2.11.0
`datatype:jackson-datatype-jsr310`	2.10.1 => want 2.11.0

Gradle uses the highest version it does find for each package. It doesn't know that the jackson packages belong together and that all of them should use the same version.

There are two possible solutions to make all jackson packages use the expected version.

solution

According to the gradle documentation the preferred solution is to add a constraints block to the dependencies. Adding a direct dependency is not the correct solution:

gradle-constraints

Often developers incorrectly fix transitive dependency issues by adding direct dependencies. To avoid this, Gradle provides the concept of dependency constraints.

Modifying the dependency resolution rules is not an option either:

gradle dependency resolve rules

If you are authoring a library, you should always prefer dependency constraints as they are published for your consumers.

constraints

The project is a library and the constraints solution look like this in the build.gradle:

ext {
    jacksonVersion = '2.11.0'
}

dependencies {
    // .. dependencies ..

    constraints {
        implementation("com.fasterxml.jackson.dataformat:jackson-dataformat-yaml:$jacksonVersion") {
            because 'use the same version for all jackson packages'
        }
        implementation("com.fasterxml.jackson.datatype:jackson-datatype-jsr310:$jacksonVersion") {
            because 'use the same version for all jackson packages'
        }
    }

}

Ok, this fixes the issue. :-)

Too bad each single package requires its own constraint (the closure with because ist not required). It would be nice to use wildcards to match all jackson packages with a single constraint:

ext {
    jacksonVersion = '2.11.0'
}

dependencies {
    // .. dependencies ..

    constraints {
        // does NOT work
        implementation("com.fasterxml.jackson.*:*:$jacksonVersion") {
            because 'use the same version for all jackson packages'
        }
    }

}

That would be a bit simpler but unfortunately it does not work.

platform

I found another solution in the gradle documentation that even uses jackson as an example:

gradle dependency version alignment.

First step is to create a metadata rule that joins all jackson packages into a platform. Jackson has a platform bom that lists all packages belonging to a platform version, and it is used to create the platform rule:

class JacksonPlatformRule implements ComponentMetadataRule {
    void execute (ComponentMetadataContext ctx) {
        ctx.details.with {
            if (id.group.startsWith ("com.fasterxml.jackson")) {
                belongsTo ("com.fasterxml.jackson:jackson-bom:${id.version}", false)
            }
        }
    }
}

I simply added the class at the end of the build.gradle for testing, but it will probably move to gradles buildSrc folder.

Second step is to activate the rule in the dependencies block:

dependencies {
    components.all(JacksonPlatformRule)

    // .. dependencies ..
}

By grouping the packages gradle now selects the jackson platform with the highest version and uses the versions listed in the bom for any jackson package.

This is also visible in the output of gradle dependencies (starting at line 4). Gradle selects the 2.11.0 platform module and upgrades all jackson packages to the platform version:

gradle dependencies (simplified)

+--- com.fasterxml.jackson.module:jackson-module-kotlin:2.11.0
|    +--- com.fasterxml.jackson.core:jackson-databind:2.11.0
|    |    +--- com.fasterxml.jackson.core:jackson-annotations:2.11.0
|    |    |    \--- com.fasterxml.jackson:jackson-bom:2.11.0
|    |    |         +--- com.fasterxml.jackson:jackson-bom:2.11.0 (*)
|    |    |         +--- com.fasterxml.jackson.core:jackson-annotations:2.11.0 (c)
|    |    |         +--- com.fasterxml.jackson.core:jackson-core:2.11.0 (c)
|    |    |         +--- com.fasterxml.jackson.core:jackson-databind:2.11.0 (c)
|    |    |         +--- com.fasterxml.jackson.module:jackson-module-kotlin:2.11.0 (c)
|    |    |         +--- com.fasterxml.jackson.dataformat:jackson-dataformat-yaml:2.11.0 (c)
|    |    |         \--- com.fasterxml.jackson.datatype:jackson-datatype-jsr310:2.11.0 (c)
|    |    +--- com.fasterxml.jackson.core:jackson-core:2.11.0
|    |    |    \--- com.fasterxml.jackson:jackson-bom:2.11.0 (*)
|    |    \--- com.fasterxml.jackson:jackson-bom:2.11.0 (*)
|    +--- com.fasterxml.jackson.core:jackson-annotations:2.11.0 (*)
|    \--- com.fasterxml.jackson:jackson-bom:2.11.0 (*)
+--- org.openapi4j:openapi-parser:1.0
|    \--- org.openapi4j:openapi-core:1.0
|         +--- com.fasterxml.jackson.core:jackson-databind:2.9.10 -> 2.11.0 (*)
|         \--- com.fasterxml.jackson.dataformat:jackson-dataformat-yaml:2.9.10 -> 2.11.0
|              +--- com.fasterxml.jackson.core:jackson-databind:2.11.0 (*)
|              +--- org.yaml:snakeyaml:1.26
|              +--- com.fasterxml.jackson.core:jackson-core:2.11.0 (*)
|              \--- com.fasterxml.jackson:jackson-bom:2.11.0 (*)
+--- io.swagger.parser.v3:swagger-parser:2.0.20
     +--- io.swagger.parser.v3:swagger-parser-v3:2.0.20
          +--- io.swagger.core.v3:swagger-models:2.1.2
          |    \--- com.fasterxml.jackson.core:jackson-annotations:2.10.1 -> 2.11.0 (*)
          +--- io.swagger.core.v3:swagger-core:2.1.2
          |    +--- com.fasterxml.jackson.core:jackson-annotations:2.10.1 -> 2.11.0 (*)
          |    +--- com.fasterxml.jackson.core:jackson-databind:2.10.1 -> 2.11.0 (*)
          |    +--- com.fasterxml.jackson.dataformat:jackson-dataformat-yaml:2.10.1 -> 2.11.0 (*)
          |    \--- com.fasterxml.jackson.datatype:jackson-datatype-jsr310:2.10.1 -> 2.11.0
          |         +--- com.fasterxml.jackson.core:jackson-annotations:2.11.0 (*)
          |         +--- com.fasterxml.jackson.core:jackson-core:2.11.0 (*)
          |         +--- com.fasterxml.jackson.core:jackson-databind:2.11.0 (*)
          |         \--- com.fasterxml.jackson:jackson-bom:2.11.0 (*)
          +--- com.fasterxml.jackson.core:jackson-annotations:2.10.2 -> 2.11.0 (*)
          +--- com.fasterxml.jackson.core:jackson-databind:2.10.2 -> 2.11.0 (*)
          \--- com.fasterxml.jackson.dataformat:jackson-dataformat-yaml:2.10.2 -> 2.11.0 (*)

conclusion

The constraints solution is easy to use on single dependencies. The platform rule is the way to go for groups of packages like jackson.

That's it.

openapi-processor-spring

Martin Hauner — Mon, 25 May 2020 17:02:02 +0000

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

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 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"
    }

}

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')

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.