OpenAPI 规范 v3.1.0
OpenAPI 规范 v3.1.0
1. OpenAPI 规范
2. 简介
3. 定义
4. 规范
4.1 版本
4.2 格式
4.3 文档结构
4.4 数据类型
4.5 富文本格式化
4.6 URI 中的相对引用
4.7 URL 中的相对引用
4.8 模式
4.8.1 OpenAPI 对象
4.8.2 Info 对象
4.8.3 Contact 对象
4.8.4 License 对象
4.8.5 Server 对象
4.8.6 Server Variable 对象
4.8.7 Components 对象
4.8.8 Paths 对象
4.8.9 Path Item 对象
4.8.10 Operation 对象
4.8.11 External Documentation 对象
4.8.12 Parameter 对象
4.8.13 Request Body 对象
4.8.14 Media Type 对象
4.8.15 Encoding 对象
4.8.16 Responses 对象
4.8.17 Response 对象
4.8.18 Callback 对象
4.8.19 Example 对象
4.8.20 Link 对象
4.8.21 Header 对象
4.8.22 Tag 对象
4.8.23 Reference 对象
4.8.24 Schema 对象
4.8.25 Discriminator 对象
4.8.26 XML 对象
4.8.27 Security Scheme 对象
4.8.28 OAuth Flows 对象
4.8.29 OAuth Flow 对象
4.8.30 Security Requirement 对象
4.9 规范扩展
4.10 安全过滤
4.8.15 Encoding 对象
创建时间: 2025-05-29 16:38
应用于单个 schema 属性的单个编码定义。
4.8.15.1 固定字段
字段名称 | 类型 | 描述 |
---|---|---|
contentType | 字符串 | 用于编码特定属性的 Content-Type。默认值取决于属性类型:对于 object - application/json ;对于 array - 默认值基于内部类型定义;对于所有其他情况,默认值为 application/octet-stream 。该值可以是特定的媒体类型(例如 application/json )、通配符媒体类型(例如 image/* )或两种类型的逗号分隔列表。 |
headers | Map[string , 头部对象 引用对象] | 允许提供其他信息作为标头的映射,例如 Content-Disposition 。Content-Type 单独描述,并且必须在本节中忽略。如果请求正文媒体类型不是 multipart ,则必须忽略此属性。** |
style | 字符串 | 根据其类型描述特定属性值将如何序列化。有关 参数对象 的 style 属性的详细信息,请参阅。行为遵循与 query 参数相同的值,包括默认值。如果请求正文媒体类型不是 application/x-www-form-urlencoded 或 multipart/form-data ,则必须忽略此属性。如果显式定义了值,则必须忽略 contentType (隐式或显式)的值。 |
explode | 布尔值 | 如果此值为 true,则类型为 array 或 object 的属性值将为数组的每个值或映射的键值对生成单独的参数。对于其他类型的属性,此属性无效。当 style 为 form 时,默认值为 true 。对于所有其他样式,默认值为 false 。如果请求正文媒体类型不是 application/x-www-form-urlencoded 或 multipart/form-data ,则必须忽略此属性。如果显式定义了值,则必须忽略 contentType (隐式或显式)的值。 |
allowReserved | 布尔值 | 确定参数值应该允许 [RFC3986] 第 2.2 节 :/?#[]@!$&'()*+,;= 定义的保留字符是否包含在内,而无需进行百分比编码。默认值为 false 。如果请求正文媒体类型不是 application/x-www-form-urlencoded 或 multipart/form-data ,则必须忽略此属性。如果显式定义了值,则必须忽略 contentType (隐式或显式)的值。 |
此对象*可以使用 规范扩展 进行扩展。
4.8.15.2 Encoding 对象示例
requestBody:
content:
multipart/form-data:
schema:
type: object
properties:
id:
# default is text/plain
type: string
format: uuid
address:
# default is application/json
type: object
properties: {}
historyMetadata:
# need to declare XML format!
description: metadata in XML format
type: object
properties: {}
profileImage: {}
encoding:
historyMetadata:
# require XML Content-Type in utf-8 encoding
contentType: application/xml; charset=utf-8
profileImage:
# only accept png/jpeg
contentType: image/png, image/jpeg
headers:
X-Rate-Limit-Limit:
description: The number of allowed requests in the current period
schema:
type: integer
最后更新: -