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

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 mapping operator instead of individual keywords:

some-key: {source type} => {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:

  # 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:
    # replace 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 object properties
    - 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:
        # replace 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 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 provides json schemas for the mapping formats at https://openapiprocessor.io/schemas/mapping/mapping-v{version}.json.