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 mappings.

All sections are optional.

type mapping structure

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

openapi-processor-mapping: v13

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 mapping

To map a source type to a destination type, it is using an ⇒ arrow as a mapping operator instead of individual keywords:

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

source type is usually a name (or type) from the OpenAPI description and target type is usually a java 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}

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

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

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

      # 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.