在OpenAPI中定义可变类型的数组

1. 概述

OpenAPI 规范（以前称为Swagger规范）帮助以标准化、机器可读的方式描述API。

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

2. 定义包含不同类型的对象数组

首先，让我们定义贯穿全文的例子。假设我们要定义一个包含以下两种对象的数组：一只狗和一头狮子：

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

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

2.1. oneOf 关键字

oneOf 关键字指定数组可以包含预定义类型集中的一种确切类型：

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

以下数组符合上述定义：

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

另一方面，混合狗和狮子是不允许的：

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

2.2. anyOf 关键字

anyOf 关键字指定数组可以包含预定义类型集中的任意组合。 这意味着只有狗、只有狮子或两者都可能是有效的数组：

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

下面显示了三个都是有效示例的数组：

{
  "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. 随意类型模式

使用随意类型模式可以定义一个包含OpenAPI规范支持的所有类型混合的数组。 它还提供了一个便捷的简写语法，即花括号*{}*：

type: array
items: {}

让我们看看上述定义的明确语法：

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

现在，我们来看一个包含字符串、数字、整数、布尔值、数组和随机对象的示例数组：

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

3. 总结

在本文中，我们了解了如何使用OpenAPI规范定义包含不同类型的数组。首先，我们学习了如何使用oneOf关键字处理包含预定义类型集中一种类型的数组。然后，我们讨论了如何使用anyOf关键字定义包含多种预定义类型混合的数组。

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