Configuration

The processor reads the configuration from the (mandatory) mapping.yaml file.It does contain some general options and the mapping type information.

A mapping yaml looks like this:

openapi-processor-mapping: v5

options:
  package-name: io.openapiprocessor.sample
  model-name-suffix: Resource
  model-type: record
  enum-type: string
  one-of-interface: true
  bean-validation: jakarta
  generated-date: true
  format-code: true
  javadoc: true

map:
   # java type mappings

The only required option is package-name. All other options or the type mappings are optional.

options:

package-name: (required) the root package name of the generated interfaces & models.The package folder tree will be created inside the targetDir (see using gradle).

Interfaces and models will be generated into the api and model subpackages of package-name.
- so the final package name of the generated interfaces will be "${package-name}.api",
- and the final package name of the generated models will be "${package-name}.model"
model-suffix-name (optional, default is empty). See below.
2023.3 model-type (optional*, default or record, default is default). Generate pojos (class with get/set property methods) or records model classes from OpenAPI schemas. See below.
bean-validation (optional, true or false, javax, jakarta) enables generation of bean validation annotations. Default is false. See Bean Validation Specification.

With the 2023.1 releases this key allows two new values to handle the package name change from bean validation v2 to v3 (javax ⇒ jakarta).
- false: disables bean validation annotations
- true: enables bean validation annotations v2, with javax package name
- javax: enables bean validation annotations v2, with javax package name
- jakarta: enables bean validation annotations v3, with jakarta package name
javadoc (optional, true or false) enables generation of JavaDoc comments from the OpenAPI description s on the API interfaces and model pojos.Default is false.
format-code (optional, true or false) enable or disable the code formatter: Default is false.
one-of-interface (optional, true or false) enables generation of marker interfaces for oneOf objects. See oneOf marker interfaces.
generated-date (optional, true or false). enable or disable the generated date on the @Genearted annotation. Default is true.

model name suffix:

optional (string, default is empty (i.e. it is disabled))

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)

    // ...
}

1	a schema name without suffix
2	the suffix configuration
3	the class name of the `Foo` schema got the configured `Resource` suffix
4	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`.

model type:

(optional*, default or record, default is default)

openapi-processor is now capable of generating java record`s instead of pojos for schemas. This is a global setting in the `mapping.yaml. It can either have the value default (which is default) to generate pojos or record to generate records.

mapping.yaml

openapi-processor-mapping: v4

options:
  model-type: record

With model-type: record the processor will generate record s like this:

Java record

package generated.model;

import com.fasterxml.jackson.annotation.JsonProperty;
import generated.support.Generated;

@Generated(value = "openapi-processor-core", version = "test")
public record Foo(
    @JsonProperty("bar")
    String bar
) {}

and without model-type or model-type: default it will create a simple pojo:

Java pojo

package generated.model;

import com.fasterxml.jackson.annotation.JsonProperty;
import generated.support.Generated;

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

    @JsonProperty("bar")
    private String bar;

    public String getBar() {
        return bar;
    }

    public void setBar(String bar) {
        this.bar = bar;
    }

}

enum type:

(optional*, default, string or framework, default is default)

mapping.yaml

openapi-processor-mapping: v5

options:
  enum-type: string

There are 3 ways to handle OpenAPI enum definitions, default, string and framework.

default generates a typical java enum class.

The other two can be used if default does not work. This is described in more detail under enums.

string does not generate an enum and simply uses java.lang.String. In case bean validation is enabled it will generate a custom bean validation annotation that checks if the incoming values is one of the enum values given in the OpenAPI description.

framework does generate a slightly different enum classes than default and a Spring ConverterFactory that can deserialize incoming values to proper enum values.

map:

Using type mapping we can tell the processor to map types (schemas) from an openapi.yaml description to a specific existing java type instead of generating a model class from the source OpenAPI type.

This is one of the core features and has his own description in mapping.