数据类型
模式的数据类型由 type
关键字定义,例如 type: string
。OpenAPI 定义了以下基本类型:
这些类型存在于大多数编程语言中,尽管它们的名称可能不同。使用这些类型,您可以描述任何数据结构。
请注意,没有 null
类型;相反,nullable
属性用作基本类型的修饰符。
可以使用额外的 type
特定关键字来细化数据类型,例如,限制字符串长度或指定可能值的enum
。
混合类型
type
接受单个值。type
作为列表在 OpenAPI 中无效(尽管它在 JSON Schema 中有效)
1# Incorrect2type:3 - string4 - integer
混合类型可以使用 oneOf
和 anyOf
来描述,它们指定了备用类型的列表。
1# Correct2oneOf:3 - type: string4 - type: integer
另请参阅任意类型。
数字
OpenAPI 有两种数字类型:number
和 integer
,其中 number
包括整数和浮点数。可选的 format
关键字作为工具使用特定数字类型的提示。
类型 |
格式 |
描述 |
---|---|---|
number | – | 任何数字。 |
number | float | 浮点数。 |
number | double | 双精度浮点数。 |
integer | – | 整数。 |
integer | int32 | 有符号 32 位整数(常用整数类型)。 |
integer | int64 | 有符号 64 位整数(long 类型)。 |
请注意,包含数字的字符串,例如“17”,被视为字符串而非数字。
最小值和最大值
使用 minimum
和 maximum
关键字来指定可能值的范围。
1type: integer2minimum: 13maximum: 20
默认情况下,minimum
和 maximum
值包含在范围内,即:
1minimum ≤ value ≤ maximum
要排除边界值,请指定 exclusiveMinimum: true
和 exclusiveMaximum: true
。例如,您可以将浮点数范围定义为 0-50 并排除 0 值。
1type: number2minimum: 03exclusiveMinimum: true4maximum: 50
exclusiveMinimum
和 exclusiveMaximum
中的“exclusive”(独占)一词表示相应边界被排除。
关键字 | 描述 |
---|---|
exclusiveMinimum: false 或未包含 |
值 ≥ minimum |
exclusiveMinimum: true |
值 > minimum |
exclusiveMaximum: false 或未包含 |
值 ≤ maximum |
exclusiveMaximum: true |
值 < maximum |
倍数
使用 multipleOf
关键字来指定一个数字必须是另一个数字的倍数。
1type: integer2multipleOf: 10
上面的例子匹配 10、20、30、0、-10、-20 等。multipleOf
可以与浮点数一起使用,但在实践中,由于精度有限或浮点运算,这可能不可靠。
1type: number2multipleOf: 2.5
multipleOf
的值必须是一个正数,即不能使用 multipleOf: -5
。
字符串
文本字符串定义为:
1type: string
字符串长度可以使用 minLength
和 maxLength
来限制。
1type: string2minLength: 33maxLength: 20
请注意,空字符串 "" 是一个有效字符串,除非指定了 minLength
或 pattern
。
字符串格式
可选的 format
修饰符提示字符串的内容和格式。OpenAPI 定义了以下内置字符串格式:
date
– RFC 3339, 第 5.6 节定义的完整日期表示法,例如 2017-07-21date-time
– RFC 3339, 第 5.6 节定义的日期时间表示法,例如 2017-07-21T17:32:28Zpassword
– 提示 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):
1ssn:2 type: string3 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# Correct2type: integer3nullable: true4
5# Incorrect6type: null7
8# Incorrect as well9type:10 - integer11 - null
上面的示例可以映射到 C# 中的可空类型 int?
和 Java 中的 java.lang.Integer
。在对象中,可空属性与可选属性不同,但某些工具可能会选择将可选属性映射到 null
值。
数组
数组定义为:
1type: array2items:3 type: string
与 JSON Schema 不同,数组中需要 items
关键字。items
的值是一个描述数组项类型和格式的模式。数组可以嵌套:
1# [ [1, 2], [3, 4] ]2type: array3items:4 type: array5 items:6 type: integer
并包含对象:
1# [ {"id": 5}, {"id": 8} ]2type: array3items:4 type: object5 properties:6 id:7 type: integer
项模式可以内联指定(如前面的示例所示),或通过 $ref
引用。
1# Array of Pets2type: array3items:4 $ref: "#/components/schemas/Pet"
混合类型数组
混合类型数组可以使用 oneOf
定义。
1# ["foo", 5, -2, "bar"]2type: array3items:4 oneOf:5 - type: string6 - type: integer
oneOf
允许内联子模式(如上面的示例所示)和引用。
1# Array of Cats and Dogs2type: array3items:4 oneOf:5 - $ref: "#/components/schemas/Cat"6 - $ref: "#/components/schemas/Dog"
任意类型数组可以定义为:
1type: array2items: {}
1# [ "hello", -2, true, [5.7], {"id": 5} ]
此处,{}
是“任意类型”模式(参见下方)。请注意,以下 items
语法无效:
1# Incorrect2items:3 - type: string4 - type: integer5
6# Incorrect as well7items:8 type:9 - string10 - integer
数组长度
您可以像这样定义数组的最小和最大长度:
1type: array2items:3 type: integer4minItems: 15maxItems: 10
如果没有 minItems
,空数组被认为是有效的。
uniqueItems
您可以使用 uniqueItems: true
来指定数组中的所有项必须是唯一的。
1type: array2items:3 type: integer4uniqueItems: true5# [1, 2, 3] – valid6# [1, 1, 3] – not valid7# [ ] – valid
对象
对象是属性/值对的集合。properties
关键字用于定义对象属性——您需要列出属性名称并为每个属性指定一个模式。
1type: object2properties:3 id:4 type: integer5 name:6 type: string
提示: 在 OpenAPI 中,对象通常定义在全局 components/schemas
部分,而不是请求和响应定义中内联。
必填属性
默认情况下,所有对象属性都是可选的。您可以在 required
列表中指定必填属性:
1type: object2properties:3 id:4 type: integer5 username:6 type: string7 name:8 type: string9required:10 - id11 - username
请注意,required
是一个对象级属性,而不是属性属性。
1type: object2properties:3 id:4 type: integer5 required: true # Wrong!6
7required: # Correct8 - id
空列表 required: []
无效。如果所有属性都是可选的,则不要指定 required
关键字。
只读和只写属性
您可以使用 readOnly
和 writeOnly
关键字将特定属性标记为只读或只写。这很有用,例如,当 GET 返回比 POST 中使用的更多属性时——您可以在 GET 和 POST 中使用相同的模式,并将额外的属性标记为 readOnly
。readOnly
属性包含在响应中但不包含在请求中,而 writeOnly
属性可以在请求中发送但不包含在响应中。
1type: object2properties:3 id:4 # Returned by GET, not used in POST/PUT/PATCH5 type: integer6 readOnly: true7 username:8 type: string9 password:10 # Used in POST/PUT/PATCH, not returned by GET11 type: string12 writeOnly: true
如果 readOnly
或 writeOnly
属性包含在 required
列表中,则 required
仅影响相关范围——仅限响应或仅限请求。也就是说,只读的必填属性仅适用于响应,而只写的必填属性仅适用于请求。
嵌套对象
一个对象可以包含嵌套对象:
1components:2 schemas:3 User:4 type: object5 properties:6 id:7 type: integer8 name:9 type: string10 contact_info:11 # The value of this property is an object12 type: object13 properties:14 email:15 type: string16 format: email17 phone:18 type: string
您可能希望将嵌套对象拆分为多个模式,并使用 $ref
引用嵌套模式。
1components:2 schemas:3 User:4 type: object5 properties:6 id:7 type: integer8 name:9 type: string10 contact_info:11 $ref: "#/components/schemas/ContactInfo"12
13 ContactInfo:14 type: object15 properties:16 email:17 type: string18 format: email19 phone:20 type: string
自由形式对象
自由形式对象(任意属性/值对)定义为:
1type: object
这等效于:
1type: object2additionalProperties: true
和:
1type: object2additionalProperties: {}
属性数量
minProperties
和 maxProperties
关键字允许您限制对象中允许的属性数量。这在使用 additionalProperties
或自由形式对象时很有用。
1type: object2minProperties: 23maxProperties: 10
在此示例中,{"id": 5, "username": "trillian"}
匹配模式,但 {"id": 5}
不匹配。
文件
与 OpenAPI 2.0 不同,OpenAPI 3.0 没有 file
类型。文件定义为字符串:
1type: string2format: binary # binary file contents
或
1type: string2format: byte # base64-encoded file contents
具体取决于所需的文件传输方法。有关更多信息,请参阅文件上传、多部分请求和返回文件的响应。
任意类型
没有类型的模式匹配任何数据类型——数字、字符串、对象等。{}
是任意类型模式的简写语法。
1components:2 schemas:3 AnyValue: {}
如果您想提供描述:
1components:2 schemas:3 AnyValue:4 description: Can be any value - string, number, boolean, array or object.
上述等效于:
1components:2 schemas:3 AnyValue:4 anyOf:5 - type: string6 - type: number7 - type: integer8 - type: boolean9 - type: array10 items: {}11 - type: object
如果需要允许 null
值,请添加 nullable: true
。
1components:2 schemas:3 AnyValue:4 nullable: true5 description: Can be any value, including `null`.