docs.openapiprocessor.io

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: v12

options:
  package-name: io.openapiprocessor.sample
  model-name-suffix: Resource
  model-type: record
  enum-type: string
  one-of-interface: true
  bean-validation: jakarta
  generated: true
  generated-date: true
  format-code: true
  javadoc: true
  clear-target-dir: false
  json-property-annotation: always
  target-dir:
    layout: standard
  base-path:
    server-url: 0
    properties-name: api.properties
logging:
  mapping: true
  mapping-target: stdout
compatibility:
  bean-validation-valid-on-reactive: false
  identifier-word-break-from-digit-to-letter: false

map:
   # java type mappings

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

options:

package-name

required (string)

the root (java) 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.

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

example

openapi-processor-mapping: v12

options:
  package-name: io.openapiprocessor.sample

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: v12

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 (string, default or record, default is default)

generate pojos (class with get/set property methods) or records model classes from OpenAPI 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.

example

mapping.yaml

openapi-processor-mapping: v12

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

}

model-accessors (new with 2025.1)

optional (boolean, true or false, default is true)

enables or disables generation of accessor methods, i.e. getter and setter. The properties are still private. This is only useful in combination with an object annotation mapping that adds the accessors. For example lombok.Getter & lombok.Setter.

This is only used with model-type: default. It is ignored with model-type: record.

example

Here is a small example that uses object annotation mapping to add the lombok getter and setter annotations to the generated class.

openapi-processor-mapping: v12

options:
  package-name: generated
  model-type: default           # i.e. pojo
  model-accessors: false        # only used if model-type is default

map:
  types:
    - type: object @ lombok.Getter
    - type: object @ lombok.Setter

The generated schema class is then looks like this, with annotations and without accessor methods.

package io.openapiprocessor.openapi.model;

import com.fasterxml.jackson.annotation.JsonProperty;
import io.openapiprocessor.openapi.support.Generated;
import java.util.UUID;
import lombok.Getter;
import lombok.Setter;

@Getter
@Setter
@Generated(value = "openapi-processor-spring")
public class Foo {

    @JsonProperty("id")
    private UUID id;

}

bean-validation

optional (boolean or string, true or false, javax, jakarta, default is false)

enables generation of bean validation annotations. See Bean Validation Specification.

to handle the package name change from bean validation v2 to v3 (javax ⇒ jakarta) it accepts the package name as an enabling value:

  • 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 (boolean, true or false, default is false)

enables generation of JavaDoc comments from the OpenAPI description s on the API interfaces and model pojos.

format-code (updated with 2025.1)

optional (boolean, true or false, google, eclipse default is false)

enable or disable the code formatter.

# mapping.yaml
options:
  format-code: false      # disable code formatter
  format-code: true       # use default google code formatter
  format-code: google     # use google code formatter, i.e. the same as "true"
  format-code: eclipse    # use eclipse code formatter

In case of google (or true) see also JDK 16+.

one-of-interface

optional (boolean, true or false, default is false)

enables generation of marker interfaces for oneOf objects. See oneOf marker interfaces.

response-interface (new with 2025.2)

optional (boolean, true or false, default is false)

enables generation of a marker interface for multiple success (i.e. 2xx) responses with the same content type.

See Endpoint content types for an example.

generated-annotation

optional (boolean, true or false, default is true)

enable or disable the @Generated annotation.

generated-date

optional (boolean, true or false, default is ´true`)

enable or disable the generated date on the @Generated annotation.

clear-target-dir

optional (boolean, true or false, default is true)

enable or disable clearing of the targetDir when the processor is writing the generated files.

See also target-dir:clear.

json-property-annotation

optional (string, always, auto, never, default is always)

control generation of the @JsonProperty annotation:

  • always: adds @JsonProperty to all schema property

  • auto: adds @JsonProperty only if it is required because the property name is no valid java identifier or the property is defined as readOnly/writeOnly in the OpenAPI description

  • never: never adds @JsonProperty to a schema property. NOTE: this may produce invalid code if the property name is not a valid java identifier.

enum type

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

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.

example

mapping.yaml

openapi-processor-mapping: v12

options:
  enum-type: string

base-path

parent key to group base path related options. See Server Url.

base-path:server-url

optional (boolean or number, false, true=0, 1, 2, …​, default is false)

enables generation of a resource file with the configured OpenAPI server/url.

To have a destination directory for generating the resource file, setting this will automatically enable the standard target dir layout.

See base-path:properties-name

base-path:properties-name

optional (string, default is api.properties)

name of the properties resource file that will contain the base-path configuration.

See base-path:server-url

target-dir

parent key to group targetDir related options.

target-dir:clear

optional (boolean, true or false, default is true)

overrides clear-target-dir

enable or disable clearing of the targetDir when the processor is writing the generated files (See also clear-target-dir).

target-dir:layout

optional (string, classic or standard, default is classic)

this controls if the targetDir is the source root folder or if there is another directory level.

  • classic, targetDir is the source root, i.e. the package structure begins in targetDir.

    targetDir
\--- io
     \--- openapiprocessor
          +--- api
          \--- model

  • standard, targetDir is the parent of source root and resource root, i.e. the package structure begins in the java subdirectory and the java`director has a `resources sibling directory.

    targetDir
+--- java
|      \--- io
|           \--- openapiprocessor
|                +--- api
|                \--- model
\--- resources

example

openapi-processor-mapping: v12

options:
  target-dir:
    layout: standard

logging:

This section contains keys for logging mapping lookups. It may be useful to locate mappings that should be used, but are not.

mapping:

optional (boolean, true or false, default is false)

enables mapping lookups logging.

mapping-target:

optional (string, logger or stdout, default is logger)

with this option it is possible to control the logging target.

If set to logger the mapping lookup gets logged at info level to slf4j. If set to stdout the mapping lookup gets written directly to stdout without slf4j.

compatibility:

This section contains keys to disable breaking changes.

identifier-word-break-from-digit-to-letter

optional (boolean, true or false, default is true)

keep the pre-2024.2 behaviour. See Identifiers.

bean-validation-valid-on-reactive

optional (boolean, true or false, default is true)

keep the pre-2024.2 behaviour. See Bean Validation.

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.