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
which is a list of global type mappings.
A single global mapping can have the following properties:
- from: .. to: .. generics: - .. - ..
from and to are required, generics is optional.
from is the type name used in the OpenAPI description and names the type that should be replaced by to. to is the fully qualified class name of the java type that should be used instead of from.
generics defines the list of types that should be used as generic type parameters to the java type given by to.
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:
- from: Book to: com.github.hauner.openapi.oap.Book
It is also possible to use a predefined OpenAPI type in the
from type of the type mapping:
- from: array to: java.util.List
This tells the processor to us a
java.util.List instead of the OpenAPI type
The generics parameter is unnecessary in this special case. The processor knows
and will automatically use the
items property of the
array as the generic type.
The basic types in OpenAPI can have a
format modifier. For example the
string type has two
date-time to provide more detail of the type. In this case the kind of date
that is represented as a
It is possible to create a global mapping that only matches a specific
format by adding the format
to the from property value separated by a ':' like this:
- from: string:date-time to: java.time.ZonedDateTime
This maps the
string type with a
date-time format from the default
java.time.ZonedDateTime. The mapping does not affect
string without a format or
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:
- from: StringPage to: org.springframework.data.domain.Page generics: - java.lang.String
The processor will replace any use of
StringPage with the to type and add the generic types
(in the given order) to the to type.
In case of the example above the processor will create
Page<String> instead of
StringPage with an
import for the generic type (.. ignoring imports on
|The processor does support only one level of generics. It is not possible to provide generic parameters to generic parameters.|
To get a more compact description it is possible to write a shorter mapping by inlining the generic types:
- from: StringPage to: org.springframework.data.domain.Page<java.lang.String>
This will generate the same code as the longer mapping version above.