知識庫 / REST RSS 訂閱

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. <em >oneOf</em> 關鍵字

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. <em>anyOf</em> 關鍵字

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

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