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 關鍵字，以及任意類型模式。

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 關鍵字來定義包含多種預定義類型的數組。

最後，我們瞭解到可以使用任意類型模式來定義可以包含任意類型的數組。