array type mapping

April 2020, last update 8. July 2023

By default, the OpenAPI array maps to a simple java array. That is probably the first thing you want to change.

To change that default mapping for example to java.util.Collection a simple global type mapping is necessary in the mapping.yaml.

Given the following openapi.yaml fragment:

paths:
  /array:
    get:
      responses:
        '200':
          description:
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string

the processor will create the following endpoint interface using the default array mapping:

@GetMapping(path = "/array", produces = {"application/json"});
String[] getArray();

To globally change the mapping of array to another collection type we just need to add a simple global type mapping to the mapping.yaml:

openapi-processor-mapping: v4

options:
  package-name: io.openapiprocessor.openapi

map:
  types:
    # map array to java.util.Collection
    - type: array => java.util.Collection

This will change the generated endpoint to:

@GetMapping(path = "/array", produces = {"application/json"});
Collection<String> getArray();

the processor assumes that the given java type has a single generic parameter and will automatically use the array's item property type as the generic parameter.

In case we have an endpoint implementation that uses another collection type, for example a Set we can override the global setting with an endpoint specific mapping like this:

openapi-processor-mapping: v4

options:
  package-name: io.openapiprocessor.openapi

map:
  types:
    # map array to java.util.Collection
    - type: array => java.util.Collection

  paths:
    # override for a specific endpoint
    /another-endpoint:
      types:
        - type: array => java.util.Set

It doesn’t make a difference in the request or response payload, but it can help in the implementation to communicate that it is a set and not just a collection.