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

options:
  package-name: io.openapiprocessor.openapi
  package-names:
    base: io.openapiprocessor.openapi # same as option.package-name
    location: io.openapiprocessor
  package-name-from-path: true
  model-name-suffix: Resource
  model-type: record
  model-unreferenced: false
  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
  identifier-prefix-invalid-enum-start: false
bean-validation:
   # bean-validation annotation to "custom" classes map
map:
   # java type mappings

The only required option is package-name or alternativly package-names.base. 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: v15

options:
  package-name: io.openapiprocessor.sample

package-names (new with 2025.3)

parent key to group package-name related options.

package-names:base

required/optional (string)

the root (java) package name of the generated interfaces & models. The package folder tree will be created inside the targetDir.

This is the same as package-name. Only one of package-name or package-names.base is required.

It takes precedence above package-name if both ar set.

package-names:location

optional (string)

package-names.location enables the creation of package names based on the file location of $ref’erenced parts of the OpenAPI description.

It is the parent package for location based package names.

Only (OpenAPI) file locations below the parent package will be generated with a location based package name. Any other (OpenAPI) file location will use package-names.base (or package-name) as the package name.

Enabling this has a few conditions:

  • to create an interface or resource in a specific package, its OpenAPI description has to be in the target package and must be reachable from the root OpenAPI description.

  • it only works with the INTERNAL OpenAPI parser (it is the default parser). It will not work with the SWAGGER OpenAPI parser.

See package-names for a description with an example. It explains the parent package and how to place OpenAPI parts into packages.

model-name-suffix

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

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

The suffix helps to

  • avoid duplicate class names in generated code and normal code

  • make 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?

  • keep 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 migrating 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: v15

options:
  package-name: io.openapiprocessor.sample
  model-name-suffix: Resource (1)
1 the suffix configuration

Java

// interface
public interface Api {

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

}

// pojos
public class FooResource { (1)

    // ...

    @JsonProperty("nested")
    private BarResource nested;

    // ...
}

public class BarResource { (2)

    // ...
}
1 the class name of the Foo schema got the configured Resource suffix
2 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: v15

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

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;

}

model-unreferenced (new with 2025.5)

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

enables generation of unreferenced component/schemas. A schema is unreferenced if it is not used in any endpoint description.

By default, openapi-processor will only generate DTOs for schemas that are referenced by an endpoint.

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 three 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: v15

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 property 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: v15

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 behavior. See Identifiers.

bean-validation-valid-on-reactive

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

keep the pre-2024.2 behavior. See Bean Validation.

identifier-prefix-invalid-enum-start

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

Invalid characters (e.g. numbers or underscore) at the start of enum values are prefixed with "V" (for value) to generate valid java identifiers. The old behaviour (pre-2025.4.1) was to strip the invalid start characters.

bean-validation: (new with 2025.5)

Opt-In for custom classes that are supported by specific bean-validation annotations.

This is a simple map of bean-validation annotation to a list of additionally supported classes.

openapi-processor-mapping: v15

bean-validation:
  jakarta.validation.constraints.DecimalMin:
    - my.custom.Integer
  jakarta.validation.constraints.DecimalMax:
    - my.custom.Integer

See Bean Validation for an explanation when this may be needed.

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.