Global mappings

Global type mapping will replace any usage of an OpenAPI type in the api description to the given java type.

It is defined like below, and it should be added to the map/types section in the mapping.yaml which is a list of global type mappings.

A single global mapping can have the following properties:

- type: {source type} => {target type}
  generics:
    - {a generic type}
    - {another generic type}

type is required.
- {source type} is the type name used in the OpenAPI description and names the type that should be replaced by {target type}. {target type} is the fully qualified class name of the java type that should be used instead of {source type}.
generics is optional. It defines the list of types that should be used as generic type parameters to the java type given by {target type}.

simple mapping

In the simplest form a global type mapping of an OpenAPI object schema like this one:

Book:
  type: object
  properties:
    isbn:
      type: string
    title:
      type: string

can be mapped to an existing Book java type/class by the following mapping:

- type: Book => io.openapiprocessor.oap.Book

It is also possible to use a predefined OpenAPI type in the from type of the type mapping:

- type: array => java.util.List

This tells the processor to us a java.util.List instead of the OpenAPI type array.

The generics parameter is unnecessary in this special case. The processor knows java.util.List and will automatically use the items property of the array as the generic type.

OpenAPIs object type has no special handling if given as the {source type} type. The processor assumes that it is just a schema name, and it will only match if there is a schema with the name "object".
global type mappings do work on OpenAPI inline schemas using the automatically generated name. This is not recommended as a small change to the api description could change the inline name and break the mapping.

mapping with format

The basic types in OpenAPI can have a format modifier. For example the string type has two modifiers date and date-time to provide more detail of the type. In this case the kind of date that is represented as a string.

It is possible to create a global mapping that only matches a specific format by adding the format to the {source type} property value separated by a ':' like this:

- type: string:date-time => java.time.ZonedDateTime

This maps the string type with a date-time format from the default java.time.OffsetDateTime to java.time.ZonedDateTime. The mapping does not affect string without a format or string with other formats.

Another example:

- type: string:uuid => java.util.UUID

mapping with generic types

Type mapping allows to use a target type that has generic parameters. The generic types are given by the generics property of the mapping. generics is a list and can contain multiple types.

For example if a StringPage schema in the OpenAPI corresponds to org.springframework.data.domain.Page<java.lang.String>, it can be mapped to the Spring type by:

- type: StringPage => org.springframework.data.domain.Page
  generics:
    - java.lang.String

The processor will replace any use of StringPage with the {target type} type and add the generic types (in the given order) to the {target type} type.

In case of the example above the processor will create Page<String> instead of StringPage with an additional import for the generic type (.. ignoring imports on java.lang).

To get a more compact description it is possible to write a shorter mapping by inlining the generic types:

- type: StringPage => org.springframework.data.domain.Page<java.lang.String>

This will generate the same code as the longer mapping version above.

nested generic types

since 2023.2

It is possible to create type mappings with nested generics types. Here are a few examples:

openapi-processor-mapping: v3

options:
  package-name: generated

map:
  types:
    - type: Foo => java.util.Map<java.lang.String, java.util.List<java.lang.String>>

  paths:
    /foo:
      responses:
        - content: application/json => java.util.Map<java.lang.String, java.lang.String>

    /foo2:
      responses:
        - content: application/json => java.util.Map<java.lang.String, java.util.List<java.lang.String>>

This is useful to map an OpenAPI dictionary description using additionalProperties to a proper java map type:

# a schema the defines a dictionary with string keys and string values
Map:
    type: object
    additionalProperties:
      type: string