mapping OpenAPI Dictionaries
January 2025
Dictionaries or maps in OpenAPI are defined with the additionalProperties keyword. To get a java Map<K,V> in the generated code an explicit mapping is necessary.
simple Dictionary
The following OpenAPI schema describes a dictionary of strings or in java terms a Map<String, String>.
components:
schemas:
Dictionary:
type: object
additionalProperties:
type: stringThe key is always a string and the type: string defines the type of the value. In this case also a string.
Adding mappings for dictionaries works as for any other OpenAPI schema. Mapping the dictionary to Map<String, String> in the generated code use would be:
openapi-processor-mapping: v9
options:
package-name: io.openapiprocessor.openapi
map:
types:
- type: Dictionary => java.util.Map<java.lang.String, java.lang.String>object Dictionary
The next example uses a schema Foo as value for the string keys:
components:
schemas:
FooDictionary:
type: object
additionalProperties:
$ref: '#/components/schemas/Foo'
Foo:
type: object
properties:
bar: string
# ...which would be mapped like this:
openapi-processor-mapping: v9
options:
package-name: io.openapiprocessor.openapi
map:
types:
- type: FooDictionary => java.util.Map<java.lang.String, io.openapiprocessor.openapi.model.Foo>or a little bit shorter using the {package-name} placeholder.
openapi-processor-mapping: v9
options:
package-name: io.openapiprocessor.openapi
map:
types:
- type: FooDictionary => java.util.Map<java.lang.String, {package-name}.model.Foo>advanced Dictionary
Dictionaries could also use an array value, for example using array of Foo as value:
components:
schemas:
FooDictionary:
type: object
additionalProperties:
type: array
items:
$ref: '#/components/schemas/Foo'
Foo:
type: object
properties:
bar: string
# ...The mapping works as expected by nesting generic types:
openapi-processor-mapping: v9
options:
package-name: io.openapiprocessor.openapi
map:
types:
- type: FooDictionary => java.util.Map<java.lang.String, java.util.Collection<{package-name}.model.Foo>>