1. Overview

1.概述

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

OpenAPI规范，以前被称为Swagger规范，有助于以标准化的、机器可读的方式描述API。

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.

在本教程中，我们将学习如何使用OpenAPI规范定义不同类型的数组。在整个文章中，我们将使用OpenAPI v3的功能。

2. Define an Array of Varying Types

2.定义一个不同类型的数组

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.

有三种方法可以定义一个可以包含这两个对象的数组：关键字oneOf、anyOf,和任意类型模式。。

2.1. oneOf Keyword

2.1.oneOf关键字

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

oneOf关键字指定数组可以精确地包含预先定义的类型集中的一个类型。

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

2.2.anyOf关键字

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:

anyOf关键字指定数组可以包含预定义类型的任何组合。这意味着只有狗，或者只有狮子，或者狗和狮子都可以构成一个有效的数组。

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

2.3.任意类型模式

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 ‘{}‘:

使用任意的类型模式可以定义一个数组，其中包含OpenAPI规范所支持的所有类型的混合体。它还带有一个由大括号”{}“组成的方便快捷的语法。

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

3.总结

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

在这篇文章中，我们已经学会了如何使用OpenAPI规范来定义不同类型的数组。

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.

首先，我们看到了如何使用关键字oneOf来定义包含一组预定义类型中的一种类型的数组。然后，我们讨论了如何用anyOf关键字定义一个包含几个预定义类型的混合数组。

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

最后，我们了解到我们可以使用任意类型模式来定义一个可以包含任意类型的数组。