type mapping structure

The type mapping is part of the mapping YAML (see Configuration) and configured under the map key. The map key contains multiple sections to define the different kinds of type mapping.

All sections are optional.

type mapping structure

The mapping file needs the following key on the top-level. The best place is the first line of the mapping.yaml file.

openapi-processor-mapping: v16

The version increases from time to time when openapi-processor requires a new or changed configuration. In case the version changes, it is mentioned in the release notes.

basic type mapping

To map a source type to a destination type, use the mapping operator: ⇒

some-key: {source type} => {target type}

Usually, source type is a name (or type) from the OpenAPI description, and target type is a java type.

since 2026.1

Alternatively, if the operator is too cryptic, it is possible to use the map keyword instead of the operator.

some-key: {source type} map {target type}

basic annotation mapping

To annotate the generated target type, use the annotation operator: @

some-key: {source type} @ {target type}

since 2026.1

Alternatively, if the operator is too cryptic, it is possible to use the annotate keyword instead of the operator.

some-key: {source type} annotate {target type}

basic interface mapping

since 2026.1

To let the generated target type implement an interface, use the interface operator: =+

some-key: {source type} =+ {target type}

Alternatively, if the operator is too cryptic, it is possible to use the implement keyword instead of the operator.

some-key: {source type} implement {target type}

full structure

The full structure of the mapping looks like this (a real mapping file will usually use just a few of the possible keys):

map:
  # global mappings, applies to all paths/endpoints

  # result wrapper, e.g. org.springframework.http.ResponseEntity
  result: {target type}

  # result-style:
  result-style: {success|all}

  # result status annotation (default true)
  result-status: {true|false}

  # single wrapper, e.g. reactor.core.publisher.Mono
  single: {target type}

  # multi wrapper, e.g. reactor.core.publisher.Flux
  multi: {target type}

  # list of global mappings
  types:
    # replace a source type with the given target type
    - type: {source type}  =>  {target type}

    # add an extra annotation to the source type
    - type: {source type}  @  {target type}

    # add an extra (marker) interface to the source type
    - type: {source type}  =+  {target type}

  # list of global schema mappings
  schemas:
    # add an extra annotation to the source type, but only on object properties
    - type: {source type}  @  {target type}

  # list of global parameter mappings
  parameters:
    - name: {parameter name}  =>  {target type}

    # add a (usually technical) parameter not described in the OpenAPI
    - add: {parameter name}  =>  {target type}

    # add an extra annotation to parameters of the source type
    - type: {source type}  @  {annotation type}

    # add an extra (marker) interface to the source type
    - type: {source type}  =+  {target type}

  # list of global content mappings, mapped by content type
  responses:
    - content: {content type}  =>  {target type}

  # path-, endpoint-, method-specific mappings
  paths:

    # a path
    /foo:
      # exclude endpoint
      exclude: {true|false}

      # path-specific result wrapper
      result: {target type}

      # result-style:
      result-style: {success|all}

      # result status annotation (default true)
      result-status: {true|false}

      # path-specific single wrapper
      single: {target type}

      # path-specific multi wrapper
      multi: {target type}

      # nullable mapping with optional initial value
      null: {target type} (= {initializer})

      # list of path-specific mappings
      types:
        # replace the source type with the given target type
        - from: {source type}  =>  {target type}

        # add an extra annotation to the source type
        - type: {source type}  @  {target type}

        # add an extra (marker) interface to the source type
        - type: {source type}  =+  {target type}

      # list of path-specific parameter mappings
      parameters:
        - name: {parameter name}  =>  {target type}

        # add a (usually technical) parameter not described in the OpenAPI
        - add: {parameter name}  =>  {target type}

        # add an extra annotation to parameters of source type
        - type: {source type}  @  {annotation type}

        # add an extra (marker) interface to the source type
        - type: {source type}  =+  {target type}

      # list of path-specific content mappings, mapped by content type
      responses:
        - content: {content type}  =>  {target type}

      # limit mapping to a specific http method (all methods are allowed)
      get:
         # ... allows any of the above keys below the endpoint path (except http methods)

      patch:
         # ...

The structure below paths is similar to an OpenAPI YAML file to make it easier to locate a specific mapping.

json schema

Some IDEs support JSON schemas to provide editing support, (auto-completion and validation) for text-based files. To support this, openapi-processor provides JSON schemas for the mapping formats at https://openapiprocessor.io/schemas/mapping/mapping-v{version}.json.