跳到内容

数据类型

模式的数据类型由 type 关键字定义,例如 type: string。OpenAPI 定义了以下基本类型:

这些类型存在于大多数编程语言中,尽管它们的名称可能不同。使用这些类型,您可以描述任何数据结构。

请注意,没有 null 类型;相反,nullable 属性用作基本类型的修饰符。

可以使用额外的 type 特定关键字来细化数据类型,例如,限制字符串长度或指定可能值的enum

混合类型

type 接受单个值。type 作为列表在 OpenAPI 中无效(尽管它在 JSON Schema 中有效)

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

混合类型可以使用 oneOfanyOf 来描述,它们指定了备用类型的列表。

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

另请参阅任意类型

数字

OpenAPI 有两种数字类型:numberinteger,其中 number 包括整数和浮点数。可选的 format 关键字作为工具使用特定数字类型的提示。

类型 格式 描述
number 任何数字。
number float 浮点数。
number double 双精度浮点数。
integer 整数。
integer int32 有符号 32 位整数(常用整数类型)。
integer int64 有符号 64 位整数(long 类型)。

请注意,包含数字的字符串,例如“17”,被视为字符串而非数字。

最小值和最大值

使用 minimummaximum 关键字来指定可能值的范围。

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

默认情况下,minimummaximum 值包含在范围内,即:

1
minimum ≤ value ≤ maximum

要排除边界值,请指定 exclusiveMinimum: trueexclusiveMaximum: true。例如,您可以将浮点数范围定义为 0-50 并排除 0 值。

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

exclusiveMinimumexclusiveMaximum 中的“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

字符串长度可以使用 minLengthmaxLength 来限制。

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

请注意,空字符串 "" 是一个有效字符串,除非指定了 minLengthpattern

字符串格式

可选的 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 匹配 petpetstorecarpet^…$ 标记强制进行精确匹配。

布尔值

type: boolean 表示两个值:truefalse。请注意,诸如“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 关键字。

只读和只写属性

您可以使用 readOnlywriteOnly 关键字将特定属性标记为只读或只写。这很有用,例如,当 GET 返回比 POST 中使用的更多属性时——您可以在 GET 和 POST 中使用相同的模式,并将额外的属性标记为 readOnlyreadOnly 属性包含在响应中但不包含在请求中,而 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

如果 readOnlywriteOnly 属性包含在 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: {}

属性数量

minPropertiesmaxProperties 关键字允许您限制对象中允许的属性数量。这在使用 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`.

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

© . All rights reserved.