数据类型

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

没有找到你要找的内容？请向社区提问
发现错误？请告诉我们