数据类型

模式的数据类型由 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 不同，OpenAPI 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`.

没有找到您想要的内容？询问社区
发现错误？告诉我们