資料類型

綱要的資料類型由 type 關鍵字定義，例如，type: string。OpenAPI 定義了以下基本類型

string（包括日期和檔案）
number
integer
boolean
array
object

這些類型存在於大多數程式設計語言中，儘管它們可能有不同的名稱。使用這些類型，您可以描述任何資料結構。

請注意，沒有 null 類型；相反，nullable 屬性用作基本類型的修飾符。

可以使用其他特定於 type 的關鍵字來精煉資料類型，例如，限制字串長度或指定可能值的enum。

混合類型

type 採用單一值。將 type 作為列表在 OpenAPI 中無效（即使在 JSON Schema 中有效）

1
# Incorrect
2
type:
3
  - string
4
  - integer

可以使用 oneOf 和 anyOf 描述混合類型，這會指定替代類型的列表

1
# Correct
2
oneOf:
3
  - type: string
4
  - type: integer

另請參閱任何類型。

數字

OpenAPI 有兩種數值類型，number 和 integer，其中 number 包括整數和浮點數。選用的 format 關鍵字可作為工具使用特定數值類型的提示

`類型`	`格式`	描述
number	–	任何數字。
number	float	浮點數。
number	double	具有雙精度的浮點數。
integer	–	整數。
integer	int32	帶正負號的 32 位元整數（常用整數類型）。
integer	int64	帶正負號的 64 位元整數（`long` 類型）。

請注意，包含數字的字串，例如「17」，會被視為字串而不是數字。

最小值和最大值

使用 minimum 和 maximum 關鍵字來指定可能值的範圍

1
type: integer
2
minimum: 1
3
maximum: 20

預設情況下，minimum 和 maximum 值會包含在範圍內，即

1
minimum ≤ value ≤ maximum

若要排除邊界值，請指定 exclusiveMinimum: true 和 exclusiveMaximum: true。例如，您可以將浮點數範圍定義為 0–50，並排除 0 值

1
type: number
2
minimum: 0
3
exclusiveMinimum: true
4
maximum: 50

exclusiveMinimum 和 exclusiveMaximum 中的「exclusive」表示對應的邊界是排除的

關鍵字	描述
`exclusiveMinimum: false` 或未包含	值 ≥ `minimum`
`exclusiveMinimum: true`	值 > `minimum`
`exclusiveMaximum: false` 或未包含	值 ≤ `maximum`
`exclusiveMaximum: true`	值 < `maximum`

倍數

使用 multipleOf 關鍵字指定一個數字必須是另一個數字的倍數

1
type: integer
2
multipleOf: 10

上述範例符合 10、20、30、0、-10、-20 等。multipleOf 可以與浮點數一起使用，但在實務上，由於浮點數運算的精度有限，這可能不可靠。

1
type: number
2
multipleOf: 2.5

multipleOf 的值必須是正數，也就是說，您不能使用 multipleOf: -5。

字串

文字字串定義如下

1
type: string

可以使用 minLength 和 maxLength 來限制字串長度

1
type: string
2
minLength: 3
3
maxLength: 20

請注意，空字串 "" 是有效字串，除非指定了 minLength 或 pattern。

字串格式

選用的 format 修飾符可作為字串內容和格式的提示。OpenAPI 定義了以下內建字串格式

date – RFC 3339 第 5.6 節定義的完整日期表示法，例如，2017-07-21
date-time – RFC 3339 第 5.6 節定義的日期時間表示法，例如，2017-07-21T17:32:28Z
password – 用於提示 UI 遮蔽輸入的內容。
byte – base64 編碼的字元，例如：U3dhZ2dlciByb2Nrcw==
binary – 二進位資料，用於描述檔案（請參閱下方的「檔案」）。

然而，format 是一個開放的值，因此您可以使用任何格式，甚至不限於 OpenAPI 規範中定義的格式，例如：

email
uuid
uri
hostname
ipv4
ipv6
以及其他格式

工具可以使用 format 來驗證輸入或將值對應到所選程式語言中的特定類型。不支援特定格式的工具可能會默認回單獨的 type，就好像沒有指定 format 一樣。

pattern

pattern 關鍵字可讓您定義字串值的正規表示式範本。只有符合此範本的值才会被接受。所使用的正規表示式語法來自 JavaScript（更準確地說，是 ECMA 262）。正規表示式區分大小寫，也就是說，[a-z] 和 [A-Z] 是不同的表示式。例如，以下模式會比對 123-45-6789 格式的社會安全號碼（SSN）：

1
ssn:
2
  type: string
3
  pattern: '^\d{3}-\d{2}-\d{4}$'

請注意，正規表示式包含在 ^…$ 符號中，其中 ^ 表示字串的開頭，而 $ 表示字串的結尾。如果沒有 ^…$，pattern 會作為部分比對，也就是說，比對任何包含指定正規表示式的字串。例如，pattern: pet 會比對 pet、petstore 和 carpet。^…$ 符號會強制執行精確比對。

布林值

type: boolean 代表兩個值：true 和 false。請注意，諸如 "true"、""、0 或 null 等真值和假值不被視為布林值。

空值

OpenAPI 3.0 沒有像 JSON Schema 中那樣明確的 null 類型，但您可以使用 nullable: true 來指定該值可能為 null。請注意，null 與空字串 "" 不同。

1
# Correct
2
type: integer
3
nullable: true
4

5
# Incorrect
6
type: null
7

8
# Incorrect as well
9
type:
10
  - integer
11
  - null

上述範例可以對應到 C# 中的可空類型 int? 和 Java 中的 java.lang.Integer。在物件中，可空屬性與可選屬性不同，但有些工具可能會選擇將可選屬性對應到 null 值。

陣列

陣列定義如下：

1
type: array
2
items:
3
  type: string

與 JSON Schema 不同，陣列中需要 items 關鍵字。items 的值是一個描述陣列項目類型和格式的結構描述。陣列可以是巢狀的：

1
# [ [1, 2], [3, 4] ]
2
type: array
3
items:
4
  type: array
5
  items:
6
    type: integer

而且可以包含物件：

1
# [ {"id": 5}, {"id": 8} ]
2
type: array
3
items:
4
  type: object
5
  properties:
6
    id:
7
      type: integer

項目結構描述可以內嵌指定（如先前的範例所示），或透過 $ref 參照：

1
# Array of Pets
2
type: array
3
items:
4
  $ref: "#/components/schemas/Pet"

混合類型陣列

可以使用 oneOf 定義混合類型陣列：

1
# ["foo", 5, -2, "bar"]
2
type: array
3
items:
4
  oneOf:
5
    - type: string
6
    - type: integer

oneOf 允許內嵌子結構描述（如上述範例）和參照：

1
# Array of Cats and Dogs
2
type: array
3
items:
4
  oneOf:
5
    - $ref: "#/components/schemas/Cat"
6
    - $ref: "#/components/schemas/Dog"

任意類型的陣列可以定義為：

1
type: array
2
items: {}

1
# [ "hello", -2, true, [5.7], {"id": 5} ]

這裡，{} 是「任意類型」的結構描述（請參閱下方的「任意類型」）。請注意，以下 items 的語法無效：

1
# Incorrect
2
items:
3
  - type: string
4
  - type: integer
5

6
# Incorrect as well
7
items:
8
  type:
9
    - string
10
    - integer

陣列長度

您可以像這樣定義陣列的最小和最大長度：

1
type: array
2
items:
3
  type: integer
4
minItems: 1
5
maxItems: 10

如果沒有 minItems，空陣列將被視為有效。

uniqueItems

您可以使用 uniqueItems: true 來指定陣列中的所有項目都必須是唯一的：

1
type: array
2
items:
3
  type: integer
4
uniqueItems: true
5
# [1, 2, 3] – valid
6
# [1, 1, 3] – not valid
7
# [ ] – valid

物件

物件是屬性/值配對的集合。properties 關鍵字用於定義物件屬性 – 您需要列出屬性名稱並為每個屬性指定結構描述。

1
type: object
2
properties:
3
  id:
4
    type: integer
5
  name:
6
    type: string

提示：在 OpenAPI 中，物件通常定義在全域 components/schemas 區段中，而不是內嵌在請求和回應定義中。

必要屬性

預設情況下，所有物件屬性都是可選的。您可以在 required 清單中指定必要屬性：

1
type: object
2
properties:
3
  id:
4
    type: integer
5
  username:
6
    type: string
7
  name:
8
    type: string
9
required:
10
  - id
11
  - username

請注意，required 是一個物件層級屬性，而不是屬性屬性：

1
type: object
2
properties:
3
  id:
4
    type: integer
5
    required: true # Wrong!
6

7
required: # Correct
8
  - id

空的清單 required: [] 無效。如果所有屬性都是可選的，請不要指定 required 關鍵字。

唯讀和唯寫屬性

您可以使用 readOnly 和 writeOnly 關鍵字將特定屬性標記為唯讀或唯寫。例如，當 GET 傳回的屬性多於 POST 中使用的屬性時，這非常有用 – 您可以在 GET 和 POST 中使用相同的結構描述，並將額外的屬性標記為 readOnly。readOnly 屬性包含在回應中，但不包含在請求中，而 writeOnly 屬性可能會在請求中傳送，但不會在回應中傳送。

1
type: object
2
properties:
3
  id:
4
    # Returned by GET, not used in POST/PUT/PATCH
5
    type: integer
6
    readOnly: true
7
  username:
8
    type: string
9
  password:
10
    # Used in POST/PUT/PATCH, not returned by GET
11
    type: string
12
    writeOnly: true

如果 readOnly 或 writeOnly 屬性包含在 required 清單中，required 只會影響相關的範圍 – 僅限回應或僅限請求。也就是說，唯讀必要屬性僅適用於回應，而唯寫必要屬性則僅適用於請求。

巢狀物件

物件可以包含巢狀物件：

1
components:
2
  schemas:
3
    User:
4
      type: object
5
      properties:
6
        id:
7
          type: integer
8
        name:
9
          type: string
10
        contact_info:
11
          # The value of this property is an object
12
          type: object
13
          properties:
14
            email:
15
              type: string
16
              format: email
17
            phone:
18
              type: string

您可能會想要將巢狀物件分割成多個結構描述，並使用 $ref 來參照巢狀結構描述：

1
components:
2
  schemas:
3
    User:
4
      type: object
5
      properties:
6
        id:
7
          type: integer
8
        name:
9
          type: string
10
        contact_info:
11
          $ref: "#/components/schemas/ContactInfo"
12

13
    ContactInfo:
14
      type: object
15
      properties:
16
        email:
17
          type: string
18
          format: email
19
        phone:
20
          type: string

自由形式物件

自由形式物件（任意屬性/值配對）定義如下：

1
type: object

這相當於：

1
type: object
2
additionalProperties: true

以及：

1
type: object
2
additionalProperties: {}

屬性數量

minProperties 和 maxProperties 關鍵字可讓您限制物件中允許的屬性數量。當使用 additionalProperties 或自由形式物件時，這會很有用。

1
type: object
2
minProperties: 2
3
maxProperties: 10

在此範例中，{"id": 5, "username": "trillian"} 符合結構描述，但 {"id": 5} 不符合。

檔案

與 OpenAPI 2.0 不同，Open API 3.0 沒有 file 類型。檔案定義為字串：

1
type: string
2
format: binary # binary file contents

或者：

1
type: string
2
format: byte # base64-encoded file contents

取決於所需的檔案傳輸方法。如需詳細資訊，請參閱「檔案上傳」、「多部分請求」和「傳回檔案的回應」。

任何類型

沒有類型的結構描述會比對任何資料類型 – 數字、字串、物件等等。{} 是任意類型結構描述的簡寫語法：

1
components:
2
  schemas:
3
    AnyValue: {}

如果您想要提供描述：

1
components:
2
  schemas:
3
    AnyValue:
4
      description: Can be any value - string, number, boolean, array or object.

以上內容相當於：

1
components:
2
  schemas:
3
    AnyValue:
4
      anyOf:
5
        - type: string
6
        - type: number
7
        - type: integer
8
        - type: boolean
9
        - type: array
10
          items: {}
11
        - type: object

如果需要允許 null 值，請新增 nullable: true：

1
components:
2
  schemas:
3
    AnyValue:
4
      nullable: true
5
      description: Can be any value, including `null`.

找不到您要的內容嗎？向社群提問
發現錯誤？請告訴我們