REST Top

Get started with Spring 5 and Spring Boot 2, through the reference Learn Spring course:

>> CHECK OUT THE COURSE

1. Overview

The OpenAPI Specification, formerly known as Swagger Specification, helps describe APIs in a standardized, machine-readable way.

In this tutorial, we'll learn how to define an array of varying types using the OpenAPI Specification. Throughout the article, we'll use the features of OpenAPI v3.

2. Define an Array of Varying Types

First, let's define the example we'll use throughout the article. We'll assume that we want to define an array containing the following two objects, representing a dog and a lion:

#dog
type: object
properties:
  barks:
    type: boolean
  likesSticks:
    type: boolean
#lion
type: object
properties:
  roars:
    type: boolean
  likesMeat:
    type: boolean

There are three ways to define an array that can contain both of these objects: the keywords oneOf, anyOf, and the arbitrary type schema.

2.1. oneOf Keyword

The oneOf keyword specifies that the array can contain exactly one type of a pre-defined set of types:

type: array
items:
  oneOf:
    - $ref: '#/components/schemas/Dog'
    - $ref: '#/components/schemas/Lion'

The following array would be a valid example for the definition above:

{
  "dogs": [
    {
      "barks": true,
      "likesSticks": true
    },
    {
      "barks": false,
      "likesSticks": true
    }
  ]
}

On the other hand, a mix of both dogs and lions wouldn't be allowed:

{
  "dogsAndLions": [
    {
      "barks": true,
      "likesSticks": true
    },
    {
      "barks": false,
      "likesSticks": true
    },
    {
      "roars": true,
      "likesMeat": true
    }
  ]
}

2.2. anyOf Keyword

The anyOf keyword specifies that the array can contain any combination of the pre-defined types. This means that only dogs, or only lions, or both dogs and lions could form a valid array:

type: array
items:
  anyOf:
    - $ref: '#/components/schemas/Dog'
    - $ref: '#/components/schemas/Lion'

The example below shows three arrays that are all valid:

{
  "onlyDogs": [
    {
      "barks": true,
      "likesSticks": true
    },
    {
      "barks": false,
      "likesSticks": true
    }
  ],
  "onlyLions": [
    {
      "roars": true,
      "likesMeat": true
    },
    {
      "roars": true,
      "likesMeat": true
    }
  ],
  "dogsAndLions": [
    {
      "barks": true,
      "likesSticks": true
    },
    {
      "barks": false,
      "likesSticks": true
    },
    {
      "roars": true,
      "likesMeat": true
    }
  ]
}

2.3. Arbitrary Type Schema

Using an arbitrary type schema allows for defining an array that contains a mix of all types that are supported by the OpenAPI Specification. It also comes with a handy shorthand syntax consisting of curly brackets ‘{}‘:

type: array
items: {}

Let's see the explicit syntax for the above definition:

type: array
items:
  anyOf:
    - type: string
    - type: number
    - type: integer
    - type: boolean
    - type: array
      items: {}
    - type: object

Now let's look at an example array containing a string, a number, an integer, a boolean, an array, and a random object:

{
  "arbitraryStuff": [
    "Hello world",
    42.1,
    42,
    true,
    [{ "name": "Randy Random" }],
    { "name": "Robbi Random" }
  ]
}

3. Conclusion

In this article, we've learned how to define an array of different types using the OpenAPI Specification.

First, we saw how to use the keyword oneOf for arrays containing one type of a pre-defined set of types. Then, we discussed how to define an array containing a mix of several pre-defined types with the anyOf keyword.

Finally, we learned we could use the arbitrary type schema to define an array that can contain arbitrary types.

REST bottom

Get started with Spring 5 and Spring Boot 2, through the Learn Spring course :

>> CHECK OUT THE COURSE
REST footer banner
guest
0 Comments
Inline Feedbacks
View all comments