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 (v2)

This is the preferred format for the mapping. It is simpler than the previous format and uses fewer keywords.

To use the new format 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: v2

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

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

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

map:

  # result wrapper
  result: {target type}

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

  # single wrapper
  single: {target type}

  # multi wrapper
  multi: {target type}

  # list of global mappings
  types:
    - type: {source type}  =>  {target type}

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

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

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

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

  # path mappings, only valid for the given path
  paths:

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

      # path specific result wrapper
      result: {target type}

      # 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:
        - from: {source type}  =>  {target type}

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

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

        # add an extra annotation to parameters of type 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 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 & validation) for text based files. To support this openapi-processor has a json schema for the v2 mapping format.

type mapping structure (v1)

This format of the mapping ist still available but should not be used anymore.