OpenAPI 规范

版本 3.1.1

本文档中的关键词“MUST”、“MUST NOT”、“REQUIRED”、“SHALL”、“SHALL NOT”、“SHOULD”、“SHOULD NOT”、“RECOMMENDED”、“NOT RECOMMENDED”、“MAY”和“OPTIONAL”仅在其全部大写出现时，才按照BCP 14 RFC2119 RFC8174 中的描述进行解释，如所示。

本文档根据Apache 许可证 2.0 版本获得许可。

引言

OpenAPI 规范 (OAS) 定义了一个标准的、与语言无关的 HTTP API 接口，允许人类和计算机无需访问源代码、文档或通过网络流量检查即可发现和理解服务的能力。正确定义后，消费者只需最少的实现逻辑即可理解远程服务并与之交互。

OpenAPI 描述可用于文档生成工具显示 API，代码生成工具生成各种编程语言的服务器和客户端，测试工具以及许多其他用例。

有关 OpenAPI 用法示例和附加文档，请访问 [[?OpenAPI-Learn]]。

有关 OpenAPI 倡议发布的其他扩展注册表和规范，以及本规范的权威呈现，请访问 spec.openapis.org。

定义

OpenAPI 描述

OpenAPI 描述 (OAD) 正式描述了 API 的表面及其语义。它由一个入口文档组成，该文档必须是 OpenAPI 文档，以及其所有引用的文档。OAD 使用并符合 OpenAPI 规范，并且 MUST 包含至少一个 paths 字段、components 字段或 webhooks 字段。

OpenAPI 文档

OpenAPI 文档是一个符合 OpenAPI 规范的独立 JSON 或 YAML 文档。与 OAS 3.*.* 兼容的 OpenAPI 文档包含一个必需的 openapi 字段，该字段指定其使用的 OAS 版本。

Schema

“schema”是对语法和结构的正式描述。本文档是 OpenAPI 规范格式的 schema；基于本文档的非权威 JSON Schema 也可在 spec.openapis.org 上获取，仅供参考。本规范还使用Schema 对象形式的 schema。

对象

当大写时，“Object”一词指本文档中由章节标题命名的任何对象。

路径模板

路径模板是指使用花括号 ({}) 分隔的模板表达式，以标记 URL 路径的一部分可使用路径参数替换。

路径中的每个模板表达式 MUST 对应于路径项本身和/或路径项的每个操作中包含的路径参数。一个例外是，如果路径项为空，例如由于 ACL 限制，则不需要匹配的路径参数。

这些路径参数的值 MUST NOT 包含 RFC3986 中描述的任何未转义的“通用语法”字符：正斜杠 (/)、问号 (?) 或井号 (#)。

媒体类型

媒体类型定义分布在多个资源中。媒体类型定义 SHOULD 符合 RFC6838。

一些可能的媒体类型定义示例

  text/plain; charset=utf-8
  application/json
  application/vnd.github+json
  application/vnd.github.v3+json
  application/vnd.github.v3.raw+json
  application/vnd.github.v3.text+json
  application/vnd.github.v3.html+json
  application/vnd.github.v3.full+json
  application/vnd.github.v3.diff
  application/vnd.github.v3.patch

HTTP 状态码

HTTP 状态码用于指示已执行操作的状态。状态码 SHOULD 从 IANA 状态码注册表中注册的可用状态码中选择。

大小写敏感性

由于 OpenAPI 规范中的大多数字段名和值都区分大小写，本文档力求指出任何不区分大小写的名称和值。然而，直接映射到 HTTP 概念的字段名和值的大小写敏感性遵循 HTTP 的大小写敏感性规则，即使本文档没有对每个概念进行说明。

未定义行为和实现定义行为

本规范认为某些情况具有未定义或实现定义的行为。

描述为未定义的行为，至少在某些情况下，可能导致与规范相矛盾的结果。当检测矛盾不可能或不切实际时，使用此描述。出于历史原因，包括规范早期版本中的模糊文本，实现 MAY 支持未定义场景。这种支持在许多情况下可能会产生正确的结果，但 NOT RECOMMENDED 依赖它，因为无法保证它在所有工具或未来的规范版本中都能正常工作，即使这些版本在其他方面严格兼容当前版本。

描述为实现定义的行为允许实现选择几种不同但符合要求的方法中的哪一种来执行。本文档记录了 API 描述作者 RECOMMENDED 避免的模糊要求，以最大限度地提高互操作性。与未定义行为不同，仅当可以保证所有相关工具支持相同的行为时，依赖实现定义行为才是安全的。

规范

版本

OpenAPI 规范使用 major.minor.patch 版本控制方案。版本字符串的 major.minor 部分（例如 3.1）SHALL 指定 OAS 功能集。.patch 版本用于纠正本文档中的错误或提供澄清，而非功能集。支持 OAS 3.1 的工具 SHOULD 与所有 OAS 3.1.* 版本兼容。工具 SHOULD NOT 考虑补丁版本，例如不对 3.1.0 和 3.1.1 进行区分。

有时，在 OAS 的 minor 版本中可能会进行不向后兼容的更改，这些更改的影响相对于所提供的好处被认为是低的。

格式

符合 OpenAPI 规范的 OpenAPI 文档本身是一个 JSON 对象，可以用 JSON 或 YAML 格式表示。

例如，如果一个字段具有数组值，将使用 JSON 数组表示法

{
  "field": [1, 2, 3]
}

规范中的所有字段名都区分大小写。这包括在映射中用作键的所有字段，除非明确指出键不区分大小写。

schema 公开了两种类型的字段：固定字段，它们具有声明的名称；以及模式化字段，它们具有声明的字段名称模式。

模式化字段在包含对象内 MUST 具有唯一的名称。

为了保留 YAML 和 JSON 格式之间的往返能力，RECOMMENDED 使用 YAML 1.2 版本以及一些附加约束。

标签 MUST 限于 YAML 的 JSON schema 规则集所允许的范围，该规则集定义了 YAML 语法的子集，与 [[JSON-Schema-2020-12|JSON Schema]] 无关。
YAML 映射中使用的键 MUST 限于标量字符串，如 YAML Failsafe schema 规则集所定义。

注意：虽然 API 可以使用 YAML 或 JSON 格式的 OpenAPI 描述来描述，但 API 请求和响应正文以及其他内容不要求是 JSON 或 YAML 格式。

OpenAPI 描述结构

OpenAPI 描述 (OAD) MAY 由单个 JSON 或 YAML 文档组成，或者由作者自行决定分成多个相互连接的部分。在后一种情况下，引用对象、路径项对象和Schema 对象的 $ref 字段，以及链接对象的 operationRef 字段，以及鉴别器对象 mapping 字段的 URI 形式，用于识别引用的元素。

在多文档 OAD 中，包含 OpenAPI 对象的文档（解析从此处开始）被称为该 OAD 的入口文档。

RECOMMENDED 将 OAD 的入口文档命名为：openapi.json 或 openapi.yaml。

解析文档

为了正确处理 Schema 对象，OAS 3.1 继承了 JSON Schema 规范草案 2020-12 的解析要求，并根据 URI 中的相对引用中指定的关于基本 URI 的适当修改。

这包括一个要求，即在认为 Schema 对象引用无法解析之前，必须解析完整的文档，以便检测可能提供引用目标或影响适当基本 URI 确定的关键词。

实现 MAY 支持以下任一种方式的完整文档解析

使用媒体类型检测 OpenAPI 或 JSON Schema 文档
通过根 openapi 字段检测 OpenAPI 文档
通过检测关键词或以其他方式根据 JSON Schema 规范成功解析文档来检测 JSON Schema 文档
根据引用的预期类型，检测在其根部包含可引用对象的文档
允许用户配置由于引用非根对象而可能加载的文档类型

在不考虑包含文档其余内容的情况下解析 OpenAPI 内容的引用片段的实现将错过改变引用目标含义和行为的关键词。特别是，未能考虑改变基本 URI 的关键词会引入安全风险，导致引用解析到意想不到的 URI，并产生不可预测的结果。虽然某些实现由于本规范过往版本的需要而支持这种解析，但在 3.1 版本中，独立解析片段的结果是未定义的，并且可能与本规范的要求相矛盾。

虽然可以构建某些 OpenAPI 描述以确保当引用被解析为独立片段时它们能正确运行，但 NOT RECOMMENDED 依赖这种方式。本规范没有明确列出这种行为安全的条件，并且不保证在 OAS 的任何未来版本中持续安全。

解析 OAS 内容片段的一种特殊情况是，如果这些片段嵌入在另一种格式中，就 OAS 而言，这种格式被称为嵌入格式。请注意，OAS 本身是 JSON Schema 的嵌入格式，JSON Schema 作为 Schema 对象嵌入。嵌入格式有责任定义如何解析嵌入内容，而未记录支持嵌入格式的 OAS 实现不能指望正确解析嵌入的 OAS 内容。

结构互操作性

OAD 中的 JSON 或 YAML 对象根据其上下文被解释为特定对象（例如操作对象、响应对象、引用对象等）。根据引用的组织方式，给定的 JSON 或 YAML 对象可以在多种不同上下文中解释

作为入口文档的根对象，它总是被解释为 OpenAPI 对象
作为文档中其父对象所暗示的对象类型
作为引用目标，对象类型与引用源的上下文匹配

如果同一个 JSON/YAML 对象被多次解析，并且各自的上下文要求它被解析为不同的对象类型，则结果行为是实现定义的，如果检测到 MAY 被视为错误。一个例子是在期望 Path Item Object 的地方引用 #/components/schemas 下的空 Schema Object，因为空对象对两种类型都有效。为了最大限度地提高互操作性，RECOMMENDED OpenAPI 描述作者避免此类情况。

解析隐式连接

本规范的若干特性要求解析与 OpenAPI 描述 (OAD) 其他部分的非 URI 连接。

这些连接在单文档 OAD 中得到明确解析，但多文档 OAD 中的解析过程是实现定义的，受本节所述约束的限制。在某些情况下，存在明确的基于 URI 的替代方案，并且 RECOMMENDED OAD 作者始终使用该替代方案

源	目标	替代方案
安全要求对象 `{name}`	安全方案对象在 Components 对象下的名称	不适用
鉴别器对象 `mapping` （隐式或显式名称语法）	Schema 对象在 Components 对象下的名称	`mapping` （显式 URI 语法）
操作对象 `tags`	标签对象 `name`（在 OpenAPI 对象的 `tags` 数组中）	不适用
链接对象 `operationId`	路径项对象 `operationId`	`operationRef`

第五个隐式连接是将 Paths 对象的模板化 URL 路径附加到相应的 Server 对象的 url 字段。这是明确的，因为只有入口文档的 Paths 对象为所描述的 API 提供 URL。

RECOMMENDED 在解析任何 Link Object operationId 时，考虑所有已解析文档中的所有 Operation Object。这要求在确定 operationId 无法解析之前解析所有引用的文档。

安全要求对象和鉴别器对象中的隐式连接依赖于组件名称，该名称是在 Components 对象中适当类型子对象中持有组件的属性名称。例如，#/components/schemas/Foo 处的 Schema 对象的组件名称是 Foo。Operation 对象中 tags 的隐式连接使用 Tag 对象的 name 字段，这些对象（如 Components 对象）位于根 OpenAPI 对象下。这意味着解析组件名称和标签名称都依赖于从正确的 OpenAPI 对象开始。

对于从引用（非入口）文档解析组件和标签名称连接，RECOMMENDED 工具从入口文档而不是当前文档解析。这允许将安全方案对象和标签对象定义在 API 的部署信息（Server 对象的顶级数组）旁边，并将其视为引用文档的访问接口。

接口方法也适用于鉴别器对象和 Schema 对象，但也可以使用 mapping 的相对 URI 引用语法将鉴别器对象的行为保留在单个文档中。

安全要求对象或操作对象的 tags 字段没有基于 URI 的替代方案。这些限制预计将在未来的版本中解决。

有关可能解决方案的示例，包括本节推荐的方案，请参阅附录 F：解析引用文档中的安全要求。鉴别器对象非 URI 映射以及操作对象的 tags 字段的行为遵循相同的原则。

请注意，隐式连接解析的任何方面都不会改变 URI 的解析方式，也不会限制其可能的目标。

数据类型

OAS 中的数据类型基于 JSON Schema 验证规范草案 2020-12 定义的类型：“null”、“boolean”、“object”、“array”、“number”、“string”或“integer”。模型使用 Schema 对象定义，该对象是 JSON Schema 规范草案 2020-12 的超集。

JSON Schema 关键词和 format 值作用于 JSON “实例”，这些实例可以是六种 JSON 数据类型中的一种：“null”、“boolean”、“object”、“array”、“number”或“string”，其中某些关键词和格式仅适用于特定类型。例如，pattern 关键词和 date-time 格式仅适用于字符串，并将其他五种类型的任何实例视为自动有效。这意味着 JSON Schema 关键词和格式不隐式要求预期类型。请使用 type 关键词来显式约束类型。

请注意，type 关键词为了方便允许 "integer" 作为值，但关键词和格式的适用性不承认整数与从其他数字中区分出不同的 JSON 类型，因为 [[RFC7159|JSON]] 本身没有进行这种区分。由于没有独立的 JSON 整数类型，JSON Schema 在数学上定义整数。这意味着 1 和 1.0 都等价，并且都被认为是整数。

数据类型格式

根据 JSON Schema 验证规范的定义，数据类型可以有一个可选的修饰符关键词：format。如该规范所述，format 默认被视为非验证性注解；验证 format 的能力因实现而异。

OpenAPI 倡议还托管了一个格式注册表，用于 OAS 用户和其他规范定义的格式。对任何注册格式的支持严格是 OPTIONAL 的，并且对一个注册格式的支持不意味着对其他任何格式的支持。

没有 format 关键词伴随的类型遵循 JSON Schema 中的类型定义。不识别特定 format 的工具 MAY 默认仅使用 type，如同未指定 format 一样。为了 JSON Schema 验证的目的，每种格式都应指定其适用的 JSON 数据类型集。在此注册表中，这些类型显示在“JSON 数据类型”列中。

OAS 定义的格式有

`格式`	JSON 数据类型	注释
`int32`	number	有符号 32 位
`int64`	number	有符号 64 位（又称 long）
`float`	number
`double`	number
`password`	string	提示模糊值。

如数据类型下所述，type: number 和 type: integer 在数据模型中都被视为数字。

处理二进制数据

OAS 可以描述原始或编码的二进制数据。

原始二进制数据用于允许未编码二进制数据的情况，例如将二进制负载作为整个 HTTP 消息体发送，或作为允许二进制部分的 multipart/* 负载的一部分
编码二进制数据用于二进制数据嵌入到纯文本格式中的情况，例如 application/json 或 application/x-www-form-urlencoded（作为消息体或在 URL 查询字符串中）。

在下表显示如何使用 Schema 对象关键词描述二进制数据时，我们使用 image/png 作为二进制媒体类型示例。任何二进制媒体类型，包括 application/octet-stream，都足以指示二进制内容。

关键词	原始	编码	注释
`type`	省略	`string`	原始二进制数据不在 `type` 范围内
`contentMediaType`	`image/png`	`image/png`	如果冗余，有时可以省略（见下文）
`contentEncoding`	省略	`base64` 或 `base64url`	允许其他编码

请注意，contentEncoding 指示的编码（它会增加数据大小以便将其表示为 7 位 ASCII 文本）与 HTTP 的 Content-Encoding 头部无关，后者指示消息体是否以及如何被压缩，并在本节描述的所有内容序列化发生之后应用。由于 HTTP 允许未编码的二进制消息体，因此没有标准化 HTTP 头部用于指示整个消息体的 base64 或类似编码。

使用 base64url 的 contentEncoding 确保 URL 编码（在查询字符串和 application/x-www-form-urlencoded 类型的消息体中必需）无需进一步编码已编码二进制数据的任何部分。

如果媒体类型已设置，contentMediaType 关键词是冗余的

作为媒体类型对象的键
在编码对象的 contentType 字段中

如果 Schema 对象将由非 OAS 感知的 JSON Schema 实现处理，即使 contentMediaType 是冗余的，包含它也可能有用。然而，如果 contentMediaType 与相关的 Media Type Object 或 Encoding Object 矛盾，则 contentMediaType SHALL 被忽略。

maxLength 关键词 MAY 用于设置流式负载长度的预期上限。该关键词可以应用于字符串数据（包括编码的二进制数据）或未编码的二进制数据。对于未编码的二进制数据，长度是八位字节数。

从 OAS 3.0 迁移二进制描述

下表展示了如何从 OAS 3.0 二进制数据描述进行迁移，并继续使用 image/png 作为示例二进制媒体类型

OAS < 3.1	OAS 3.1	注释
`type: string` `format: binary`	`contentMediaType: image/png`	如果冗余，可以省略，通常会产生一个空的 Schema 对象
`type: string` `format: byte`	`type: string` `contentMediaType: image/png` `contentEncoding: base64`	请注意，可以使用 `base64url` 来避免重新编码 base64 字符串以使其 URL 安全

富文本格式

在整个规范中，description 字段都注明支持 CommonMark markdown 格式。OpenAPI 工具在渲染富文本时，MUST 至少支持 CommonMark 0.27 所述的 markdown 语法。工具 MAY 选择忽略某些 CommonMark 或扩展功能以解决安全问题。

虽然将 CommonMark 0.27 作为最低要求意味着工具 MAY 选择在其之上实现扩展，但请注意，任何此类扩展根据定义都是实现定义的，并且不会具有互操作性。OpenAPI 描述作者 SHOULD 考虑仅提供最低支持的工具将如何渲染使用此类扩展的文本。

API 描述 URI 中的相对引用

在 OpenAPI 描述中用作引用，或指向外部文档或其他补充信息（如许可证）的 URI，被解析为标识符，并被本规范描述为URI。如解析文档中所述，本规范继承了 JSON Schema 规范草案 2020-12 关于加载文档并将其与其预期 URI 关联的要求，这些 URI 可能与其当前位置不匹配。此功能用于在开发或测试环境中工作而无需更改 URI，以及在受限制的网络配置或安全策略下工作。

请注意，某些 URI 字段由于历史原因被命名为 url，但这些字段的描述性文本使用了正确的“URI”术语。

除非另有说明，所有作为 URI 的字段 MAY 是 RFC3986 定义的相对引用。

Schema 对象中的相对引用，包括任何显示为 $id 值的引用，都使用最近的父 $id 作为基本 URI，如 JSON Schema 规范草案 2020-12 所述。

其他对象中以及没有父 schema 包含 $id 的 Schema 对象中的相对 URI 引用，MUST 使用引用文档的基本 URI 进行解析，该基本 URI 根据 [[RFC3986]] 第 5.1.2 – 5.1.4 节确定。实际上，这通常是文档的检索 URI，MAY 根据其当前实际位置或用户提供的预期位置确定。

如果 URI 包含片段标识符，则应根据引用文档的片段解析机制解析该片段。如果引用文档的表示是 JSON 或 YAML，则片段标识符 SHOULD 根据 RFC6901 被解释为 JSON 指针。

CommonMark 超链接中的相对引用在其渲染上下文中解析，这可能与 API 描述的上下文不同。

API URL 中的相对引用

API 端点根据定义作为位置访问，并被本规范描述为URL。

除非另有说明，所有作为 URL 的字段 MAY 是 RFC3986 定义的相对引用。除非另有说明，相对引用使用 Server 对象中定义的 URL 作为基本 URL 进行解析。请注意，这些 URL 本身 MAY 相对于引用文档。

Schema

本节描述了 OpenAPI 描述格式的结构。此文本是该格式唯一的规范性描述。spec.openapis.org 上托管了一个 JSON Schema，供参考。如果 JSON Schema 与本节不同，则本节 MUST 被视为权威。

在以下描述中，如果一个字段没有明确REQUIRED或用 MUST 或 SHALL 描述，则可以视为 OPTIONAL。

OpenAPI 对象

这是OpenAPI 描述的根对象。

固定字段

字段名称	类型	描述
openapi	`string`	REQUIRED。此字符串 MUST 是 OpenAPI 文档所使用的 OpenAPI 规范的版本号。工具 SHOULD 使用 `openapi` 字段来解释 OpenAPI 文档。这与 API `info.version` 字符串无关。
info	信息对象	REQUIRED。提供关于 API 的元数据。工具 MAY 根据需要使用这些元数据。
jsonSchemaDialect	`string`	此 OAS 文档中包含的 Schema 对象内 `$schema` 关键词的默认值。这 MUST 是 URI 的形式。
servers	[服务器对象]	Server 对象数组，提供到目标服务器的连接信息。如果未提供 `servers` 字段，或者它是一个空数组，则默认值将是一个 Server 对象，其 url 值为 `/`。
paths	路径对象	API 可用的路径和操作。
webhooks	Map[`string`, 路径项对象]	作为此 API 的一部分 MAY 接收的入站 webhook，以及 API 消费者 MAY 选择实现的 webhook。与 `callbacks` 功能密切相关，本节描述了除了 API 调用之外（例如通过带外注册）发起的请求。键名是引用每个 webhook 的唯一字符串，而（可选引用的）路径项对象描述了可能由 API 提供商发起的请求和预期响应。示例可用。
components	组件对象	用于保存 OpenAPI 描述的各种对象的元素。
security	[安全要求对象]	声明可在整个 API 中使用的安全机制。值列表包括可用的替代安全要求对象。只需满足其中一个安全要求对象即可授权请求。单个操作可以覆盖此定义。该列表可以是不完整的，甚至可以是空的或不存在的。要使安全性显式可选，可以在数组中包含一个空安全要求（`{}`）。
tags	[标签对象]	OpenAPI 描述使用的标签列表，附带额外元数据。标签的顺序可用于反映其在解析工具中的顺序。操作对象使用的所有标签不必都声明。未声明的标签 MAY 随机组织或根据工具逻辑组织。列表中的每个标签名称 MUST 是唯一的。
externalDocs	外部文档对象	附加外部文档。

此对象 MAY 使用规范扩展进行扩展。

信息对象

该对象提供有关 API 的元数据。客户端 MAY 在需要时使用这些元数据，并且 MAY 为了方便在编辑或文档生成工具中显示。

固定字段

字段名称	类型	描述
title	`string`	REQUIRED。API 的标题。
summary	`string`	API 的简短摘要。
description	`string`	API 的描述。CommonMark 语法 MAY 用于富文本表示。
termsOfService	`string`	API 服务条款的 URI。这 MUST 是 URI 的形式。
contact	联系信息对象	公开 API 的联系信息。
license	许可证对象	公开 API 的许可证信息。
version	`string`	REQUIRED。OpenAPI 文档的版本（与OpenAPI 规范版本、所描述 API 的版本或 OpenAPI 描述的版本不同）。

此对象 MAY 使用规范扩展进行扩展。

信息对象示例

{
  "title": "Example Pet Store App",
  "summary": "A pet store manager.",
  "description": "This is an example server for a pet store.",
  "termsOfService": "https://example.com/terms/",
  "contact": {
    "name": "API Support",
    "url": "https://www.example.com/support",
    "email": "[email protected]"
  },
  "license": {
    "name": "Apache 2.0",
    "url": "https://apache.ac.cn/licenses/LICENSE-2.0.html"
  },
  "version": "1.0.1"
}

title: Example Pet Store App
summary: A pet store manager.
description: This is an example server for a pet store.
termsOfService: https://example.com/terms/
contact:
  name: API Support
  url: https://www.example.com/support
  email: [email protected]
license:
  name: Apache 2.0
  url: https://apache.ac.cn/licenses/LICENSE-2.0.html
version: 1.0.1

联系信息对象

公开 API 的联系信息。

固定字段

字段名称	类型	描述
name	`string`	联系人/组织的识别名称。
url	`string`	联系信息的 URI。这 MUST 是 URI 的形式。
email	`string`	联系人/组织的电子邮件地址。这 MUST 是电子邮件地址的形式。

此对象 MAY 使用规范扩展进行扩展。

联系对象示例

{
  "name": "API Support",
  "url": "https://www.example.com/support",
  "email": "[email protected]"
}

name: API Support
url: https://www.example.com/support
email: [email protected]

许可证对象

公开 API 的许可证信息。

固定字段

字段名称	类型	描述
name	`string`	REQUIRED。API 使用的许可证名称。
identifier	`string`	API 的 SPDX 许可证表达式。`identifier` 字段与 `url` 字段互斥。
url	`string`	API 使用的许可证的 URI。这 MUST 是 URI 的形式。`url` 字段与 `identifier` 字段互斥。

此对象 MAY 使用规范扩展进行扩展。

许可证对象示例

{
  "name": "Apache 2.0",
  "identifier": "Apache-2.0"
}

name: Apache 2.0
identifier: Apache-2.0

服务器对象

表示服务器的对象。

固定字段

字段名称	类型	描述
url	`string`	REQUIRED。目标主机的 URL。此 URL 支持服务器变量，MAY 是相对的，以指示主机位置相对于提供包含 Server 对象的文档的位置。当变量在 `{`花括号`}` 中命名时，将进行变量替换。
description	`string`	描述 URL 指定的主机的可选字符串。CommonMark 语法 MAY 用于富文本表示。
variables	Map[`string`, 服务器变量对象]	变量名与其值之间的映射。该值用于服务器 URL 模板中的替换。

此对象 MAY 使用规范扩展进行扩展。

服务器对象示例

单个服务器将描述为

{
  "url": "https://development.gigantic-server.com/v1",
  "description": "Development server"
}

url: https://development.gigantic-server.com/v1
description: Development server

以下展示了如何描述多个服务器，例如在 OpenAPI 对象的 servers 中

{
  "servers": [
    {
      "url": "https://development.gigantic-server.com/v1",
      "description": "Development server"
    },
    {
      "url": "https://staging.gigantic-server.com/v1",
      "description": "Staging server"
    },
    {
      "url": "https://api.gigantic-server.com/v1",
      "description": "Production server"
    }
  ]
}

servers:
  - url: https://development.gigantic-server.com/v1
    description: Development server
  - url: https://staging.gigantic-server.com/v1
    description: Staging server
  - url: https://api.gigantic-server.com/v1
    description: Production server

以下展示了如何将变量用于服务器配置

{
  "servers": [
    {
      "url": "https://{username}.gigantic-server.com:{port}/{basePath}",
      "description": "The production API server",
      "variables": {
        "username": {
          "default": "demo",
          "description": "A user-specific subdomain. Use `demo` for a free sandbox environment."
        },
        "port": {
          "enum": ["8443", "443"],
          "default": "8443"
        },
        "basePath": {
          "default": "v2"
        }
      }
    }
  ]
}

servers:
  - url: https://{username}.gigantic-server.com:{port}/{basePath}
    description: The production API server
    variables:
      username:
        # note! no enum here means it is an open value
        default: demo
        description: A user-specific subdomain. Use `demo` for a free sandbox environment.
      port:
        enum:
          - '8443'
          - '443'
        default: '8443'
      basePath:
        # open meaning there is the opportunity to use special base paths as assigned by the provider, default is `v2`
        default: v2

服务器变量对象

表示用于服务器 URL 模板替换的服务器变量的对象。

固定字段

字段名称	类型	描述
enum	[`string`]	一组字符串值的枚举，如果替换选项来自有限集合，则使用该枚举。数组 MUST NOT 为空。
default	`string`	REQUIRED。用于替换的默认值，如果没有提供替代值，则 SHALL 发送此值。如果定义了 `enum`，则该值 MUST 存在于枚举的值中。请注意，此行为与 Schema 对象的 `default` 关键词不同，后者记录接收方的行为而不是将值插入数据中。
description	`string`	服务器变量的可选描述。CommonMark 语法 MAY 用于富文本表示。

此对象 MAY 使用规范扩展进行扩展。

组件对象

包含用于 OAS 不同方面的可重用对象集。在 Components 对象中定义的所有对象都不会对 API 产生影响，除非它们从 Components 对象外部被显式引用。

固定字段

字段名称	类型	描述
schemas	Map[`string`, Schema 对象]	用于保存可重用 Schema 对象的对象。
responses	Map[`string`, 响应对象 \| 引用对象]	用于保存可重用响应对象的对象。
parameters	Map[`string`, 参数对象 \| 引用对象]	用于保存可重用参数对象的对象。
examples	Map[`string`, 示例对象 \| 引用对象]	用于保存可重用示例对象的对象。
requestBodies	Map[`string`, 请求体对象 \| 引用对象]	用于保存可重用请求体对象的对象。
headers	Map[`string`, 头部对象 \| 引用对象]	用于保存可重用头部对象的对象。
securitySchemes	Map[`string`, 安全方案对象 \| 引用对象]	用于保存可重用安全方案对象的对象。
links	Map[`string`, 链接对象 \| 引用对象]	用于保存可重用链接对象的对象。
callbacks	Map[`string`, 回调对象 \| 引用对象]	用于保存可重用回调对象的对象。
pathItems	Map[`string`, 路径项对象]	用于保存可重用路径项对象的对象。

此对象 MAY 使用规范扩展进行扩展。

上述所有声明的固定字段都是对象，其键 MUST 匹配正则表达式：^[a-zA-Z0-9\.\-_]+$。

字段名称示例

User
User_1
User_Name
user-name
my.org.User

组件对象示例

"components": {
  "schemas": {
    "GeneralError": {
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "format": "int32"
        },
        "message": {
          "type": "string"
        }
      }
    },
    "Category": {
      "type": "object",
      "properties": {
        "id": {
          "type": "integer",
          "format": "int64"
        },
        "name": {
          "type": "string"
        }
      }
    },
    "Tag": {
      "type": "object",
      "properties": {
        "id": {
          "type": "integer",
          "format": "int64"
        },
        "name": {
          "type": "string"
        }
      }
    }
  },
  "parameters": {
    "skipParam": {
      "name": "skip",
      "in": "query",
      "description": "number of items to skip",
      "required": true,
      "schema": {
        "type": "integer",
        "format": "int32"
      }
    },
    "limitParam": {
      "name": "limit",
      "in": "query",
      "description": "max records to return",
      "required": true,
      "schema" : {
        "type": "integer",
        "format": "int32"
      }
    }
  },
  "responses": {
    "NotFound": {
      "description": "Entity not found."
    },
    "IllegalInput": {
      "description": "Illegal input for operation."
    },
    "GeneralError": {
      "description": "General Error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/GeneralError"
          }
        }
      }
    }
  },
  "securitySchemes": {
    "api_key": {
      "type": "apiKey",
      "name": "api-key",
      "in": "header"
    },
    "petstore_auth": {
      "type": "oauth2",
      "flows": {
        "implicit": {
          "authorizationUrl": "https://example.org/api/oauth/dialog",
          "scopes": {
            "write:pets": "modify pets in your account",
            "read:pets": "read your pets"
          }
        }
      }
    }
  }
}

components:
  schemas:
    GeneralError:
      type: object
      properties:
        code:
          type: integer
          format: int32
        message:
          type: string
    Category:
      type: object
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
    Tag:
      type: object
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
  parameters:
    skipParam:
      name: skip
      in: query
      description: number of items to skip
      required: true
      schema:
        type: integer
        format: int32
    limitParam:
      name: limit
      in: query
      description: max records to return
      required: true
      schema:
        type: integer
        format: int32
  responses:
    NotFound:
      description: Entity not found.
    IllegalInput:
      description: Illegal input for operation.
    GeneralError:
      description: General Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/GeneralError'
  securitySchemes:
    api_key:
      type: apiKey
      name: api-key
      in: header
    petstore_auth:
      type: oauth2
      flows:
        implicit:
          authorizationUrl: https://example.org/api/oauth/dialog
          scopes:
            write:pets: modify pets in your account
            read:pets: read your pets

路径对象

保存到各个端点及其操作的相对路径。该路径附加到服务器对象的 URL，以构建完整的 URL。Paths 对象 MAY 为空，由于访问控制列表 (ACL) 约束。

模式化字段

字段模式	类型	描述
/{path}	路径项对象	指向单个端点的相对路径。字段名 MUST 以正斜杠 (`/`) 开头。该路径附加（无相对 URL 解析）到从服务器对象的 `url` 字段扩展的 URL，以构建完整的 URL。路径模板是允许的。在匹配 URL 时，具体（非模板）路径将在其模板对应路径之前匹配。具有相同层级但不同模板名称的模板路径 MUST NOT 存在，因为它们是相同的。在模糊匹配的情况下，由工具决定使用哪一个。

此对象 MAY 使用规范扩展进行扩展。

路径模板匹配

假设以下路径，具体定义 /pets/mine 如果使用将首先匹配

  /pets/{petId}
  /pets/mine

以下路径被认为是相同且无效的

  /pets/{petId}
  /pets/{name}

以下可能导致模糊解析

  /{entity}/me
  /books/{id}

路径对象示例

{
  "/pets": {
    "get": {
      "description": "Returns all pets from the system that the user has access to",
      "responses": {
        "200": {
          "description": "A list of pets.",
          "content": {
            "application/json": {
              "schema": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/pet"
                }
              }
            }
          }
        }
      }
    }
  }
}

/pets:
  get:
    description: Returns all pets from the system that the user has access to
    responses:
      '200':
        description: A list of pets.
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/pet'

路径项对象

描述单个路径上可用的操作。路径项 MAY 为空，由于ACL 约束。路径本身仍然暴露给文档查看器，但他们不会知道哪些操作和参数可用。

固定字段

字段名称	类型	描述
$ref	`string`	允许对此路径项进行引用定义。该值 MUST 是 URI 的形式，并且引用的结构 MUST 是路径项对象的形式。如果 Path Item Object 字段在定义的对象和引用的对象中都出现，则行为是未定义的。请参阅解析相对引用的规则。注意： `$ref` 与相邻属性的行为可能会在未来版本的本规范中发生变化，以使其更接近引用对象的行为。
summary	`string`	一个可选的字符串摘要，旨在应用于此路径中的所有操作。
description	`string`	一个可选的字符串描述，旨在应用于此路径中的所有操作。CommonMark 语法 MAY 用于富文本表示。
get	操作对象	此路径上 GET 操作的定义。
put	操作对象	此路径上 PUT 操作的定义。
post	操作对象	此路径上 POST 操作的定义。
delete	操作对象	此路径上 DELETE 操作的定义。
options	操作对象	此路径上 OPTIONS 操作的定义。
head	操作对象	此路径上 HEAD 操作的定义。
patch	操作对象	此路径上 PATCH 操作的定义。
trace	操作对象	此路径上 TRACE 操作的定义。
servers	[服务器对象]	用于服务此路径中所有操作的备用 `servers` 数组。如果在 OpenAPI 对象级别指定了 `servers` 数组，则此值将覆盖它。
parameters	[参数对象 \| 引用对象]	适用于此路径下所有操作的参数列表。这些参数可以在操作级别被覆盖，但不能在那里被删除。该列表 MUST NOT 包含重复的参数。唯一参数由 name 和 location 的组合定义。该列表可以使用引用对象来链接到 OpenAPI 对象的 `components.parameters` 中定义的参数。

此对象 MAY 使用规范扩展进行扩展。

路径项对象示例

{
  "get": {
    "description": "Returns pets based on ID",
    "summary": "Find pets by ID",
    "operationId": "getPetsById",
    "responses": {
      "200": {
        "description": "pet response",
        "content": {
          "*/*": {
            "schema": {
              "type": "array",
              "items": {
                "$ref": "#/components/schemas/Pet"
              }
            }
          }
        }
      },
      "default": {
        "description": "error payload",
        "content": {
          "text/html": {
            "schema": {
              "$ref": "#/components/schemas/ErrorModel"
            }
          }
        }
      }
    }
  },
  "parameters": [
    {
      "name": "id",
      "in": "path",
      "description": "ID of pet to use",
      "required": true,
      "schema": {
        "type": "array",
        "items": {
          "type": "string"
        }
      },
      "style": "simple"
    }
  ]
}

get:
  description: Returns pets based on ID
  summary: Find pets by ID
  operationId: getPetsById
  responses:
    '200':
      description: pet response
      content:
        '*/*':
          schema:
            type: array
            items:
              $ref: '#/components/schemas/Pet'
    default:
      description: error payload
      content:
        text/html:
          schema:
            $ref: '#/components/schemas/ErrorModel'
parameters:
  - name: id
    in: path
    description: ID of pet to use
    required: true
    schema:
      type: array
      items:
        type: string
    style: simple

操作对象

描述路径上的单个 API 操作。

固定字段

字段名称	类型	描述
tags	[`string`]	用于 API 文档控制的标签列表。标签可用于按资源或任何其他限定符对操作进行逻辑分组。
summary	`string`	操作功能的简短摘要。
description	`string`	操作行为的详细解释。CommonMark 语法 MAY 用于富文本表示。
externalDocs	外部文档对象	此操作的附加外部文档。
operationId	`string`	用于识别操作的唯一字符串。ID MUST 在 API 中描述的所有操作中是唯一的。`operationId` 值区分大小写。工具和库 MAY 使用 `operationId` 唯一标识一个操作，因此，RECOMMENDED 遵循常见的编程命名约定。
parameters	[参数对象 \| 引用对象]	适用于此操作的参数列表。如果参数已在路径项定义，则新定义将覆盖它但不能删除它。该列表 MUST NOT 包含重复的参数。唯一参数由 name 和 location 的组合定义。该列表可以使用引用对象来链接到 OpenAPI 对象的 `components.parameters` 中定义的参数。
requestBody	请求体对象 \| 引用对象	适用于此操作的请求体。`requestBody` 在 HTTP 方法中得到完全支持，其中 HTTP 1.1 规范 RFC7231 明确定义了请求体的语义。在 HTTP 规范模糊的其他情况（例如 GET、HEAD 和 DELETE）下，`requestBody` 是允许的，但没有明确定义的语义，并且 SHOULD 尽可能避免使用。
responses	响应对象	执行此操作后返回的可能响应列表。
callbacks	Map[`string`, 回调对象 \| 引用对象]	与父操作相关的带外回调的映射。键是 Callback 对象的唯一标识符。映射中的每个值都是一个 Callback 对象，它描述了可能由 API 提供商发起的请求和预期的响应。
deprecated	`布尔值`	声明此操作已弃用。消费者 SHOULD 避免使用已声明的操作。默认值为 `false`。
security	[安全要求对象]	声明此操作可使用的安全机制。值列表包括可用的替代安全要求对象。只需满足其中一个安全要求对象即可授权请求。要使安全性可选，可以在数组中包含一个空安全要求（`{}`）。此定义覆盖任何已声明的顶级 `security`。要删除顶级安全声明，可以使用一个空数组。
servers	[服务器对象]	服务此操作的备用 `servers` 数组。如果在路径项对象或 OpenAPI 对象级别指定了 `servers` 数组，则此值将覆盖它。

此对象 MAY 使用规范扩展进行扩展。

操作对象示例

{
  "tags": ["pet"],
  "summary": "Updates a pet in the store with form data",
  "operationId": "updatePetWithForm",
  "parameters": [
    {
      "name": "petId",
      "in": "path",
      "description": "ID of pet that needs to be updated",
      "required": true,
      "schema": {
        "type": "string"
      }
    }
  ],
  "requestBody": {
    "content": {
      "application/x-www-form-urlencoded": {
        "schema": {
          "type": "object",
          "properties": {
            "name": {
              "description": "Updated name of the pet",
              "type": "string"
            },
            "status": {
              "description": "Updated status of the pet",
              "type": "string"
            }
          },
          "required": ["status"]
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Pet updated.",
      "content": {
        "application/json": {},
        "application/xml": {}
      }
    },
    "405": {
      "description": "Method Not Allowed",
      "content": {
        "application/json": {},
        "application/xml": {}
      }
    }
  },
  "security": [
    {
      "petstore_auth": ["write:pets", "read:pets"]
    }
  ]
}

tags:
  - pet
summary: Updates a pet in the store with form data
operationId: updatePetWithForm
parameters:
  - name: petId
    in: path
    description: ID of pet that needs to be updated
    required: true
    schema:
      type: string
requestBody:
  content:
    application/x-www-form-urlencoded:
      schema:
        type: object
        properties:
          name:
            description: Updated name of the pet
            type: string
          status:
            description: Updated status of the pet
            type: string
        required:
          - status
responses:
  '200':
    description: Pet updated.
    content:
      application/json: {}
      application/xml: {}
  '405':
    description: Method Not Allowed
    content:
      application/json: {}
      application/xml: {}
security:
  - petstore_auth:
      - write:pets
      - read:pets

外部文档对象

允许引用外部资源以获取扩展文档。

固定字段

字段名称	类型	描述
description	`string`	目标文档的描述。CommonMark 语法 MAY 用于富文本表示。
url	`string`	REQUIRED。目标文档的 URI。这 MUST 是 URI 的形式。

此对象 MAY 使用规范扩展进行扩展。

外部文档对象示例

{
  "description": "Find more info here",
  "url": "https://example.com"
}

description: Find more info here
url: https://example.com

参数对象

描述单个操作参数。

唯一参数由 name 和 location 的组合定义。

有关百分比编码问题的详细说明，包括与 application/x-www-form-urlencoded 查询字符串格式的交互，请参阅附录 E。

参数位置

in 字段指定了四种可能的参数位置

path - 与路径模板一起使用，其中参数值实际上是操作 URL 的一部分。这不包括 API 的主机或基本路径。例如，在 /items/{itemId} 中，路径参数是 itemId。
query - 附加到 URL 的参数。例如，在 /items?id=### 中，查询参数是 id。
header - 作为请求一部分的自定义头部。请注意，RFC7230 指出头部名称不区分大小写。
cookie - 用于向 API 传递特定的 cookie 值。

固定字段

参数序列化的规则通过两种方式之一指定。Parameter 对象 MUST 包含 content 字段或 schema 字段，但不能同时包含两者。有关将各种类型的值转换为字符串表示形式的讨论，请参阅附录 B。

常用固定字段

这些字段 MAY 与 content 或 schema 一起使用。

字段名称	类型	描述
name	`string`	REQUIRED。参数的名称。参数名区分大小写。如果 `in` 是 `"path"`，则 `name` 字段 MUST 对应于 Paths 对象的 path 字段中出现的模板表达式。有关详细信息，请参阅路径模板。如果 `in` 是 `"header"` 并且 `name` 字段是 `"Accept"`、`"Content-Type"` 或 `"Authorization"`，则参数定义 SHALL 被忽略。对于所有其他情况，`name` 对应于 `in` 字段使用的参数名称。
in	`string`	REQUIRED。参数的位置。可能的值有 `"query"`、`"header"`、`"path"` 或 `"cookie"`。
description	`string`	参数的简要描述。这可能包含使用示例。CommonMark 语法 MAY 用于富文本表示。
required	`布尔值`	确定此参数是否强制。如果参数位置是 `"path"`，则此字段是 REQUIRED 并且其值 MUST 为 `true`。否则，该字段 MAY 包含，其默认值为 `false`。
deprecated	`布尔值`	指定参数已弃用，SHOULD 逐步停止使用。默认值为 `false`。
allowEmptyValue	`布尔值`	如果为 `true`，客户端 MAY 传递一个零长度字符串值来代替原本会完全省略的参数，服务器 SHOULD 将其解释为参数未使用。默认值为 `false`。如果使用了 `style`，并且如果行为是不适用（无法序列化），则 `allowEmptyValue` 的值 SHALL 被忽略。此字段与参数的 Schema 对象之间的交互是实现定义的。此字段仅对 `query` 参数有效。NOT RECOMMENDED 使用此字段，它很可能在后续修订中被移除。

此对象 MAY 使用规范扩展进行扩展。

请注意，虽然当 in 为 "header" 时，"Cookie" 作为 name 并非禁止，但以这种方式定义 cookie 参数的效果是未定义的；请改用 in: "cookie"。

与 `schema` 一起使用的固定字段

对于更简单的场景，schema 和 style 可以描述参数的结构和语法。当 example 或 examples 与 schema 字段一起提供时，示例 SHOULD 匹配指定的 schema 并遵循为参数规定的序列化策略。example 和 examples 字段互斥，如果其中任何一个存在，它 SHALL 覆盖 schema 中的任何 example。

对于 in: "cookie" 参数、使用 HTTP 头部参数（后跟 ; 的 name=value 对）作为值的 in: "header" 参数，或值可能包含非 URL 安全字符的 in: "header" 参数，NOT RECOMMENDED 使用 schema 进行序列化；详细信息请参阅附录 D。

字段名称	类型	描述
style	`string`	描述参数值如何根据参数值类型进行序列化。默认值（基于 `in` 的值）：对于 `"query"` - `"form"`；对于 `"path"` - `"simple"`；对于 `"header"` - `"simple"`；对于 `"cookie"` - `"form"`。
explode	`布尔值`	当此项为 true 时，类型为 `array` 或 `object` 的参数值将为数组的每个值或映射的键值对生成单独的参数。对于其他类型的参数，此字段无效。当 `style` 为 `"form"` 时，默认值为 `true`。对于所有其他样式，默认值为 `false`。请注意，尽管 `deepObject` 的默认值为 `false`，但 `false` 与 `deepObject` 的组合是未定义的。
allowReserved	`布尔值`	当此项为 true 时，参数值使用保留扩展进行序列化，如 RFC6570 所定义，它允许 RFC3986 的保留字符集以及百分比编码的三元组不变地通过，同时仍然对所有其他不允许的字符（包括百分比编码三元组之外的 `%`）进行百分比编码。应用程序仍然负责对在查询字符串中不允许（`[`、`]`、`#`）或在 `application/x-www-form-urlencoded` 中具有特殊含义（`-`、`&`、`+`）的保留字符进行百分比编码；详情请参阅附录 C 和 E。此字段仅适用于 `in` 值为 `query` 的参数。默认值为 `false`。
schema	Schema 对象	定义参数所用类型的 schema。
example	任意	参数可能值的示例；请参阅使用示例。
examples	Map[ `string`, 示例对象 \| 引用对象]	参数可能值的示例；请参阅使用示例。

另请参阅附录 C：使用基于 RFC6570 的序列化以获取额外指导。

与 `content` 一起使用的固定字段

对于更复杂的场景，content 字段可以定义参数的媒体类型和 schema，并提供其使用示例。对于 schema 策略不适用的 in: "header" 和 in: "cookie" 参数，RECOMMENDED 使用 text/plain 媒体类型的 content。

字段名称	类型	描述
content	Map[`string`, 媒体类型对象]	包含参数表示形式的映射。键是媒体类型，值描述它。该映射 MUST 只包含一个条目。

样式值

为了支持序列化简单参数的常用方式，定义了一组 style 值。

`样式`	`type`	`in`	注释
matrix	`primitive`, `array`, `object`	`path`	RFC6570 定义的路径样式参数
label	`primitive`, `array`, `object`	`path`	RFC6570 定义的标签样式参数
simple	`primitive`, `array`, `object`	`path`, `header`	RFC6570 定义的简单样式参数。此选项将 OpenAPI 2.0 中的 `collectionFormat` 替换为 `csv` 值。
form	`primitive`, `array`, `object`	`query`, `cookie`	RFC6570 定义的表单样式参数。此选项将 OpenAPI 2.0 中的 `collectionFormat` 替换为 `csv` 值（当 `explode` 为 false 时）或 `multi` 值（当 `explode` 为 true 时）。
spaceDelimited	`array`, `object`	`query`	空格分隔的数组值或对象属性和值。此选项替换了 OpenAPI 2.0 中 `collectionFormat` 等于 `ssv` 的情况。
pipeDelimited	`array`, `object`	`query`	管道分隔的数组值或对象属性和值。此选项替换了 OpenAPI 2.0 中 `collectionFormat` 等于 `pipes` 的情况。
deepObject	`object`	`query`	允许使用表单参数表示具有标量属性的对象。数组或对象属性的表示未定义。

有关百分比编码的讨论，包括何时需要对分隔符进行百分比编码以及处理与百分比编码数据冲突的选项，请参阅附录 E。

样式示例

假设名为 color 的参数具有以下值之一

   string -> "blue"
   array -> ["blue", "black", "brown"]
   object -> { "R": 100, "G": 200, "B": 150 }

下表显示了每种值的不同序列化示例，如使用 example 或 examples 关键词所示。

值 empty 表示空字符串，与 allowEmptyValue 字段无关
标记为 n/a 的组合的行为是未定义的
undefined 列取代了本规范早期版本中的 empty 列，以便更好地与 RFC6570 术语保持一致，该术语将某些值（包括但不限于 null）描述为具有特殊处理的“未定义”值；值得注意的是，空字符串不是未定义的
对于 form 以及非 RFC6570 查询字符串样式 spaceDelimited、pipeDelimited 和 deepObject，每个示例都以 ? 为前缀显示，如同它是唯一的查询参数一样；有关从多个参数构建查询字符串的更多信息，请参阅附录 C，有关 form 和 cookie 参数的警告，请参阅附录 D。
请注意，? 前缀不适用于序列化 application/x-www-form-urlencoded HTTP 消息体，并且在使用该上下文时，必须将其剥离（如果手动构建字符串）或不添加；更多信息请参阅编码对象。
示例按照 RFC6570 和 RFC3986 的要求进行百分比编码；关于百分比编码的详细讨论，包括为什么未编码的 | (%7C)、[ (%5B) 和 ] (%5D) 在某些环境中看似有效但实际上不符合规范，请参阅附录 E。

`样式`	`展开`	`未定义`	`string`	`数组`	`object`
matrix	false	;颜色	;颜色=蓝色	;颜色=蓝色,黑色,棕色	;颜色=R,100,G,200,B,150
matrix	true	;颜色	;颜色=蓝色	;颜色=蓝色;颜色=黑色;颜色=棕色	;R=100;G=200;B=150
label	false	.	.蓝色	.蓝色,黑色,棕色	.R,100,G,200,B,150
label	true	.	.蓝色	.蓝色.黑色.棕色	.R=100.G=200.B=150
simple	false	空	蓝色	蓝色,黑色,棕色	R,100,G,200,B,150
simple	true	空	蓝色	蓝色,黑色,棕色	R=100,G=200,B=150
form	false	?颜色=	?颜色=蓝色	?颜色=蓝色,黑色,棕色	?颜色=R,100,G,200,B,150
form	true	?颜色=	?颜色=蓝色	?颜色=蓝色&颜色=黑色&颜色=棕色	?R=100&G=200&B=150
spaceDelimited	false	不适用	不适用	?颜色=蓝色%20黑色%20棕色	?颜色=R%20100%20G%20200%20B%20150
spaceDelimited	true	不适用	不适用	不适用	不适用
pipeDelimited	false	不适用	不适用	?颜色=蓝色%7C黑色%7C棕色	?颜色=R%7C100%7CG%7C200%7CB%7C150
pipeDelimited	true	不适用	不适用	不适用	不适用
deepObject	false	不适用	不适用	不适用	不适用
deepObject	true	不适用	不适用	不适用	?颜色%5BR%5D=100&颜色%5BG%5D=200&颜色%5BB%5D=150

参数对象示例

一个包含 64 位整数数组的头部参数

{
  "name": "token",
  "in": "header",
  "description": "token to be passed as a header",
  "required": true,
  "schema": {
    "type": "array",
    "items": {
      "type": "integer",
      "format": "int64"
    }
  },
  "style": "simple"
}

name: token
in: header
description: token to be passed as a header
required: true
schema:
  type: array
  items:
    type: integer
    format: int64
style: simple

一个字符串值的路径参数

{
  "name": "username",
  "in": "path",
  "description": "username to fetch",
  "required": true,
  "schema": {
    "type": "string"
  }
}

name: username
in: path
description: username to fetch
required: true
schema:
  type: string

一个可选的字符串值查询参数，通过重复查询参数允许多个值

{
  "name": "id",
  "in": "query",
  "description": "ID of the object to fetch",
  "required": false,
  "schema": {
    "type": "array",
    "items": {
      "type": "string"
    }
  },
  "style": "form",
  "explode": true
}

name: id
in: query
description: ID of the object to fetch
required: false
schema:
  type: array
  items:
    type: string
style: form
explode: true

一个自由形式的查询参数，允许特定类型的未定义参数

{
  "in": "query",
  "name": "freeForm",
  "schema": {
    "type": "object",
    "additionalProperties": {
      "type": "integer"
    }
  },
  "style": "form"
}

in: query
name: freeForm
schema:
  type: object
  additionalProperties:
    type: integer
style: form

一个使用 content 定义序列化的复杂参数

{
  "in": "query",
  "name": "coordinates",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "required": ["lat", "long"],
        "properties": {
          "lat": {
            "type": "number"
          },
          "long": {
            "type": "number"
          }
        }
      }
    }
  }
}

in: query
name: coordinates
content:
  application/json:
    schema:
      type: object
      required:
        - lat
        - long
      properties:
        lat:
          type: number
        long:
          type: number

请求体对象

描述单个请求体。

固定字段

字段名称	类型	描述
描述	`string`	对请求体的简要描述。这可以包含使用示例。可以使用 CommonMark 语法进行富文本表示。
内容	Map[`string`, 媒体类型对象]	必需。请求体的内容。键是媒体类型或媒体类型范围，值描述了它。对于匹配多个键的请求，只有最具体的键适用。例如，`"text/plain"` 会覆盖 `"text/*"`
必需	`布尔值`	确定请求体在请求中是否必需。默认为 `false`。

此对象 MAY 使用规范扩展进行扩展。

请求体示例

一个带有引用模式定义的请求体。

{
  "description": "user to add to the system",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/User"
      },
      "examples": {
        "user": {
          "summary": "User Example",
          "externalValue": "https://foo.bar/examples/user-example.json"
        }
      }
    },
    "application/xml": {
      "schema": {
        "$ref": "#/components/schemas/User"
      },
      "examples": {
        "user": {
          "summary": "User example in XML",
          "externalValue": "https://foo.bar/examples/user-example.xml"
        }
      }
    },
    "text/plain": {
      "examples": {
        "user": {
          "summary": "User example in Plain text",
          "externalValue": "https://foo.bar/examples/user-example.txt"
        }
      }
    },
    "*/*": {
      "examples": {
        "user": {
          "summary": "User example in other format",
          "externalValue": "https://foo.bar/examples/user-example.whatever"
        }
      }
    }
  }
}

description: user to add to the system
content:
  application/json:
    schema:
      $ref: '#/components/schemas/User'
    examples:
      user:
        summary: User example
        externalValue: https://foo.bar/examples/user-example.json
  application/xml:
    schema:
      $ref: '#/components/schemas/User'
    examples:
      user:
        summary: User example in XML
        externalValue: https://foo.bar/examples/user-example.xml
  text/plain:
    examples:
      user:
        summary: User example in plain text
        externalValue: https://foo.bar/examples/user-example.txt
  '*/*':
    examples:
      user:
        summary: User example in other format
        externalValue: https://foo.bar/examples/user-example.whatever

媒体类型对象

每个媒体类型对象为其键标识的媒体类型提供模式和示例。

当提供了 example 或 examples 时，示例应与指定的模式匹配，并以媒体类型及其编码所指定的正确格式呈现。example 和 examples 字段互斥，如果其中任何一个存在，它将覆盖模式中的任何 example。有关指定示例的不同方式（包括非 JSON/YAML 值）的进一步指导，请参阅处理示例。

固定字段

字段名称	类型	描述
模式	Schema 对象	定义请求、响应、参数或头部内容的模式。
示例	任意	媒体类型示例；请参阅处理示例。
示例	Map[ `string`, 示例对象 \| 引用对象]	媒体类型示例；请参阅处理示例。
编码	映射[`string`, 编码对象]	属性名称与其编码信息之间的映射。键（即属性名称）必须作为属性存在于模式中。`encoding` 字段仅适用于请求体对象，并且仅当媒体类型为 `multipart` 或 `application/x-www-form-urlencoded` 时。如果未为属性提供编码对象，则行为由编码对象中记录的默认值确定。

此对象 MAY 使用规范扩展进行扩展。

媒体类型示例

{
  "application/json": {
    "schema": {
      "$ref": "#/components/schemas/Pet"
    },
    "examples": {
      "cat": {
        "summary": "An example of a cat",
        "value": {
          "name": "Fluffy",
          "petType": "Cat",
          "color": "White",
          "gender": "male",
          "breed": "Persian"
        }
      },
      "dog": {
        "summary": "An example of a dog with a cat's name",
        "value": {
          "name": "Puma",
          "petType": "Dog",
          "color": "Black",
          "gender": "Female",
          "breed": "Mixed"
        }
      },
      "frog": {
        "$ref": "#/components/examples/frog-example"
      }
    }
  }
}

application/json:
  schema:
    $ref: '#/components/schemas/Pet'
  examples:
    cat:
      summary: An example of a cat
      value:
        name: Fluffy
        petType: Cat
        color: White
        gender: male
        breed: Persian
    dog:
      summary: An example of a dog with a cat's name
      value:
        name: Puma
        petType: Dog
        color: Black
        gender: Female
        breed: Mixed
    frog:
      $ref: '#/components/examples/frog-example'

文件上传的注意事项

与 OpenAPI 2.0 不同，OAS 3.x 中的 file 输入/输出内容采用与任何其他模式类型相同的语义进行描述。

与 OAS 3.0 不同，format 关键字在 OAS 3.1 中对模式的内容编码没有影响。取而代之的是，使用 JSON Schema 的 contentEncoding 和 contentMediaType 关键字。有关如何使用这些关键字建模各种场景以及如何从以前的 format 用法进行迁移，请参阅处理二进制数据。

示例

以二进制（八位字节流）传输的内容可以省略 schema

# a PNG image as a binary file:
content:
  image/png: {}

# an arbitrary binary file:
content:
  application/octet-stream: {}

# arbitrary JSON without constraints beyond being syntactically valid:
content:
  application/json: {}

这些示例适用于文件上传的输入载荷或响应载荷。

在 POST 操作中提交文件的 requestBody 可能如下例所示

requestBody:
  content:
    application/octet-stream: {}

此外，还可以指定特定的媒体类型

# multiple, specific media types may be specified:
requestBody:
  content:
    # a binary file of type png or jpeg
    image/jpeg: {}
    image/png: {}

要上传多个文件，必须使用 multipart 媒体类型，如示例：包含多个文件的多部分表单所示。

支持 x-www-form-urlencoded 请求体

有关指导和示例，无论是否包含 encoding 字段，请参阅编码 x-www-form-urlencoded 媒体类型。

`multipart` 内容的特殊注意事项

有关进一步的指导和示例，无论是否包含 encoding 字段，请参阅编码 multipart 媒体类型。

编码对象

应用于单个模式属性的单个编码定义。有关将各种类型的值转换为字符串表示形式的讨论，请参阅附录 B。

属性与 multipart 部分相关联，通过使用 Content-Disposition: form-data 的 name 参数，并与 application/x-www-form-urlencoded 相关联，通过使用查询字符串参数名称。在这两种情况下，它们的顺序都是实现定义的。

有关表单媒体类型百分比编码问题的详细检查，请参阅附录 E。

固定字段

常用固定字段

这些字段可以与下一节中定义的 RFC6570 风格的序列化字段一起使用，也可以不使用。

字段名称	类型	描述
contentType	`string`	编码特定属性的 `Content-Type`。值是逗号分隔的列表，每个元素都是一个特定的媒体类型（例如 `image/png`）或一个通配符媒体类型（例如 `image/*`）。默认值取决于属性类型，如以下表格所示。
headers	Map[`string`, 头部对象 \| 引用对象]	允许以头部形式提供额外信息的映射。`Content-Type` 单独描述，在本节中应被忽略。如果请求体媒体类型不是 `multipart`，则此字段应被忽略。

此对象 MAY 使用规范扩展进行扩展。

contentType 的默认值如下，其中 contentEncoding 列中的 n/a 表示 contentEncoding 的存在或值无关紧要

`type`	`contentEncoding`	默认 `contentType`
不存在	不适用	`application/octet-stream`
`string`	存在	`application/octet-stream`
`string`	不存在	`text/plain`
`number`, `integer`, 或 `boolean`	不适用	`text/plain`
`object`	不适用	`application/json`
`数组`	不适用	根据 `items` 模式的 `type`

如何处理 null 类型的值取决于 null 值的序列化方式。如果 null 值完全省略，则 contentType 不相关。有关数据类型转换选项的讨论，请参阅附录 B。

RFC6570 样式序列化的固定字段

字段名称	类型	描述
style	`string`	描述特定属性值如何根据其类型进行序列化。有关`style`字段的详细信息，请参阅参数对象。其行为遵循与 `query` 参数相同的值，包括默认值。请注意，查询字符串中使用的初始 `?` 不用于 `application/x-www-form-urlencoded` 消息体中，并且必须移除（如果使用 RFC6570 实现）或根本不添加（如果手动构建字符串）。如果请求体媒体类型不是 `application/x-www-form-urlencoded` 或 `multipart/form-data`，则此字段应被忽略。如果明确定义了值，则`contentType`的值（隐式或显式）应被忽略。
explode	`布尔值`	当此值为 true 时，`array` 或 `object` 类型的属性值将为数组的每个值或映射的键值对生成单独的参数。对于其他类型的属性，此字段无效。当`style`为 `"form"` 时，默认值为 `true`。对于所有其他样式，默认值为 `false`。请注意，尽管 `deepObject` 的默认值为 `false`，但 `false` 与 `deepObject` 的组合是未定义的。如果请求体媒体类型不是 `application/x-www-form-urlencoded` 或 `multipart/form-data`，则此字段应被忽略。如果明确定义了值，则`contentType`的值（隐式或显式）应被忽略。
allowReserved	`布尔值`	当此值为 true 时，参数值使用保留扩展进行序列化，如 RFC6570 定义，它允许 RFC3986 的保留字符集以及百分比编码的三元组保持不变，同时仍对所有其他不允许的字符（包括百分比编码三元组之外的 `%`）进行百分比编码。应用程序仍负责对查询字符串中不允许的保留字符（`[`、`]`、`#`）或在 `application/x-www-form-urlencoded` 中具有特殊含义的字符（`-`、`&`、`+`）进行百分比编码；详见附录 C 和 E。默认值为 `false`。如果请求体媒体类型不是 `application/x-www-form-urlencoded` 或 `multipart/form-data`，则此字段应被忽略。如果明确定义了值，则`contentType`的值（隐式或显式）应被忽略。

另请参阅附录 C：使用 RFC6570 实现，获取额外指导，包括 RFC6570 的百分比编码规则与 multipart/form-data 媒体类型之间的交互所导致的困难。

请注意，存在至少一个明确值的 style、explode 或 allowReserved，等同于使用带有 in: "query" 参数对象的 schema。这三个字段都不存在，则等同于使用 content，但媒体类型通过 contentType 指定而不是通过媒体类型对象指定。

编码 `x-www-form-urlencoded` 媒体类型

要通过 RFC1866 使用表单 URL 编码提交内容，请在请求体对象下的媒体类型对象中使用 application/x-www-form-urlencoded 媒体类型。此配置意味着，当传递给服务器时，请求体必须按照 RFC1866 进行编码，之后任何复杂对象都已序列化为字符串表示形式。

有关表单媒体类型百分比编码问题的详细检查，请参阅附录 E。

示例：带 JSON 值的 URL 编码表单

当没有 encoding 字段时，序列化策略基于编码对象的默认值。

requestBody:
  content:
    application/x-www-form-urlencoded:
      schema:
        type: object
        properties:
          id:
            type: string
            format: uuid
          address:
            # complex types are stringified to support RFC 1866
            type: object
            properties: {}

此示例中，考虑 id 为 f81d4fae-7dec-11d0-a765-00a0c91e6bf6，US 风格地址（带 ZIP+4）如下

{
  "streetAddress": "123 Example Dr.",
  "city": "Somewhere",
  "state": "CA",
  "zip": "99999+1234"
}

假设 JSON 值采用最紧凑的表示形式（去除不必要的空白），我们期望看到以下请求体，其中空格字符已被 + 替换，而 +、"、{ 和 } 分别被百分比编码为 %2B、%22、%7B 和 %7D

id=f81d4fae-7dec-11d0-a765-00a0c91e6bf6&address=%7B%22streetAddress%22:%22123+Example+Dr.%22,%22city%22:%22Somewhere%22,%22state%22:%22CA%22,%22zip%22:%2299999%2B1234%22%7D

请注意，根据编码对象的默认行为，id 关键字被视为 text/plain，并按原样序列化。如果将其视为 application/json，则序列化的值将是一个包含引号的 JSON 字符串，并被百分比编码为 %22。

这里是 id 参数（不带 address），它被序列化为 application/json 而不是 text/plain，然后根据 RFC1866 进行编码

id=%22f81d4fae-7dec-11d0-a765-00a0c91e6bf6%22

示例：带有二进制值的 URL 编码表单

请注意，application/x-www-form-urlencoded 是一种文本格式，需要对任何二进制数据进行 base64 编码

requestBody:
  content:
    application/x-www-form-urlencoded:
      schema:
        type: object
        properties:
          name:
            type: string
          icon:
            # The default with "contentEncoding" is application/octet-stream,
            # so we need to set image media type(s) in the Encoding Object.
            type: string
            contentEncoding: base64url
  encoding:
    icon:
      contentType: image/png, image/jpeg

给定一个名称 example 和一个用于 icon 的实心红色 2x2 像素 PNG，这将生成如下请求体

name=example&icon=iVBORw0KGgoAAAANSUhEUgAAAAIAAAACCAIAAAD91JpzAAAABGdBTUEAALGPC_xhBQAAADhlWElmTU0AKgAAAAgAAYdpAAQAAAABAAAAGgAAAAAAAqACAAQAAAABAAAAAqADAAQAAAABAAAAAgAAAADO0J6QAAAAEElEQVQIHWP8zwACTGCSAQANHQEDqtPptQAAAABJRU5ErkJggg%3D%3D

请注意，即使使用“URL 安全”的 contentEncoding: base64url，末尾的 = 填充字符也需要进行百分比编码。根据 RFC4648，一些 base64 解码实现可能能够使用不带填充的字符串。但是，这不作保证，因此保留填充并依赖百分比解码可能更具互操作性。

编码 `multipart` 媒体类型

在将表单作为请求体传输时，通常使用 multipart/form-data 作为 Content-Type。与 OpenAPI 2.0 不同，在使用 multipart 内容时，schema 是定义操作输入参数的必需项。这支持复杂的结构以及支持多个文件上传的机制。

form-data 处置及其 name 参数对于 multipart/form-data 是强制性的 (RFC7578)。数组属性通过对多个部分应用相同的 name 来处理，这符合 RFC7578 关于每个表单字段提供多个值的建议。有关非 ASCII 部分名称的指导，请参阅 RFC7578。

各种其他 multipart 类型，最显著的是 multipart/mixed (RFC2046)，既不要求也不禁止特定的 Content-Disposition 值，这意味着必须注意确保所使用的任何值都得到所有相关软件的支持。目前无法将模式属性与 multipart/mixed 等媒体类型中未命名、有序的部分关联起来，但当 Content-Disposition: form-data 与 name 参数一起使用时，实现可以选择支持此类类型。

请注意，通常对于 multipart 媒体类型 (RFC2046) 以及特别是 multi-part/form-data (RFC7578) 可使用的头部存在重大限制。

另请注意，Content-Transfer-Encoding 在 multipart/form-data (RFC7578) 中已弃用，因为 HTTP 中支持二进制数据。

+ 为多部分字段使用 contentEncoding 等同于指定一个编码对象，其中包含一个 headers 字段，该字段包含 Content-Transfer-Encoding，其模式要求使用 contentEncoding 中的值。+ 如果为多部分字段使用 contentEncoding，而该字段的编码对象包含一个 headers 字段，该字段包含 Content-Transfer-Encoding，其模式不允许 contentEncoding 中的值，则序列化和解析的结果是未定义的。

请注意，如处理二进制数据中所述，如果编码对象的 contentType（无论是显式设置还是通过其默认值规则隐式设置）与模式对象中的 contentMediaType 不一致，则应忽略 contentMediaType。因此，并且由于编码对象的 contentType 默认规则未考虑模式对象的 contentMediaType，所以不建议将 contentMediaType 与编码对象一起使用。

有关表单媒体类型百分比编码问题的详细检查，请参阅附录 E。

示例：基本多部分表单

当不使用 encoding 字段时，编码由编码对象的默认值确定

requestBody:
  content:
    multipart/form-data:
      schema:
        type: object
        properties:
          id:
            # default for primitives without a special format is text/plain
            type: string
            format: uuid
          profileImage:
            # default for string with binary format is `application/octet-stream`
            type: string
            format: binary
          addresses:
            # default for arrays is based on the type in the `items`
            # subschema, which is an object, so `application/json`
            type: array
            items:
              $ref: '#/components/schemas/Address'

示例：带编码对象的多部分表单

使用 encoding，我们可以为二进制数据设置更具体的类型，或为复杂值设置非 JSON 格式。我们还可以描述每个部分的头部。

requestBody:
  content:
    multipart/form-data:
      schema:
        type: object
        properties:
          id:
            # default is `text/plain`
            type: string
            format: uuid
          addresses:
            # default based on the `items` subschema would be
            # `application/json`, but we want these address objects
            # serialized as `application/xml` instead
            description: addresses in XML format
            type: array
            items:
              $ref: '#/components/schemas/Address'
          profileImage:
            # default is application/octet-stream, but we can declare
            # a more specific image type or types
            type: string
            format: binary
      encoding:
        addresses:
          # require XML Content-Type in utf-8 encoding
          # This is applied to each address part corresponding
          # to each address in he array
          contentType: application/xml; charset=utf-8
        profileImage:
          # only accept png or jpeg
          contentType: image/png, image/jpeg
          headers:
            X-Rate-Limit-Limit:
              description: The number of allowed requests in the current period
              schema:
                type: integer

示例：包含多个文件的多部分表单

根据 RFC7578，单个表单字段的多个文件使用相同名称（本例中为 file）上传到每个文件部分

requestBody:
  content:
    multipart/form-data:
      schema:
        properties:
          # The property name 'file' will be used for all files.
          file:
            type: array
            items: {}

如编码对象的 contentType 字段文档所示，items 的空模式表示媒体类型为 application/octet-stream。

响应对象

操作预期响应的容器。该容器将 HTTP 响应代码映射到预期响应。

文档不一定需要涵盖所有可能的 HTTP 响应代码，因为它们可能无法提前知道。但是，文档应涵盖成功的操作响应和任何已知错误。

default 可以用作所有未由响应对象单独涵盖的 HTTP 代码的默认响应对象。

响应对象必须至少包含一个响应代码，如果只提供一个响应代码，则它应该是成功操作调用的响应。

固定字段

字段名称	类型	描述
默认	响应对象 \| 引用对象	除为特定 HTTP 响应代码声明的响应之外的其他响应的文档。使用此字段涵盖未声明的响应。

模式化字段

字段模式	类型	描述
HTTP 状态码	响应对象 \| 引用对象	任何 HTTP 状态码都可以用作属性名称，但每个代码只能有一个属性，以描述该 HTTP 状态码的预期响应。为兼容 JSON 和 YAML，此字段必须用引号括起来（例如，“200”）。要定义响应代码范围，此字段可以包含大写通配符 `X`。例如，`2XX` 表示 `200` 到 `299` 之间的所有响应代码。只允许以下范围定义：`1XX`、`2XX`、`3XX`、`4XX` 和 `5XX`。如果使用显式代码定义响应，则显式代码定义优先于该代码的范围定义。

此对象 MAY 使用规范扩展进行扩展。

响应对象示例

成功操作的 200 响应和针对其他操作的默认响应（暗示错误）

{
  "200": {
    "description": "a pet to be returned",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/Pet"
        }
      }
    }
  },
  "default": {
    "description": "Unexpected error",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/ErrorModel"
        }
      }
    }
  }
}

'200':
  description: a pet to be returned
  content:
    application/json:
      schema:
        $ref: '#/components/schemas/Pet'
default:
  description: Unexpected error
  content:
    application/json:
      schema:
        $ref: '#/components/schemas/ErrorModel'

响应对象

描述 API 操作的单个响应，包括设计时基于响应到操作的静态 links。

固定字段

字段名称	类型	描述
描述	`string`	必需。对响应的描述。可以使用 CommonMark 语法进行富文本表示。
头部	Map[`string`, 头部对象 \| 引用对象]	将头部名称映射到其定义。RFC7230 规定头部名称不区分大小写。如果响应头部定义为 `"Content-Type"`，则应忽略它。
内容	Map[`string`, 媒体类型对象]	一个映射，包含潜在响应载荷的描述。键是媒体类型或媒体类型范围，值描述了它。对于匹配多个键的响应，只有最具体的键适用。例如，`"text/plain"` 会覆盖 `"text/*"`
链接	Map[`string`, 链接对象 \| 引用对象]	一个操作链接的映射，可以从响应中跟随。映射的键是链接的短名称，遵循组件对象名称的命名约束。

此对象 MAY 使用规范扩展进行扩展。

响应对象示例

复杂类型数组的响应

{
  "description": "A complex object array response",
  "content": {
    "application/json": {
      "schema": {
        "type": "array",
        "items": {
          "$ref": "#/components/schemas/VeryComplexType"
        }
      }
    }
  }
}

description: A complex object array response
content:
  application/json:
    schema:
      type: array
      items:
        $ref: '#/components/schemas/VeryComplexType'

字符串类型的响应

{
  "description": "A simple string response",
  "content": {
    "text/plain": {
      "schema": {
        "type": "string"
      }
    }
  }
}

description: A simple string response
content:
  text/plain:
    schema:
      type: string

带头部的纯文本响应

{
  "description": "A simple string response",
  "content": {
    "text/plain": {
      "schema": {
        "type": "string"
      },
      "example": "whoa!"
    }
  },
  "headers": {
    "X-Rate-Limit-Limit": {
      "description": "The number of allowed requests in the current period",
      "schema": {
        "type": "integer"
      }
    },
    "X-Rate-Limit-Remaining": {
      "description": "The number of remaining requests in the current period",
      "schema": {
        "type": "integer"
      }
    },
    "X-Rate-Limit-Reset": {
      "description": "The number of seconds left in the current period",
      "schema": {
        "type": "integer"
      }
    }
  }
}

description: A simple string response
content:
  text/plain:
    schema:
      type: string
    example: 'whoa!'
headers:
  X-Rate-Limit-Limit:
    description: The number of allowed requests in the current period
    schema:
      type: integer
  X-Rate-Limit-Remaining:
    description: The number of remaining requests in the current period
    schema:
      type: integer
  X-Rate-Limit-Reset:
    description: The number of seconds left in the current period
    schema:
      type: integer

无返回值的响应

{
  "description": "object created"
}

description: object created

回调对象

与父操作相关的可能带外回调的映射。映射中的每个值都是一个路径项对象，它描述了一组可能由 API 提供者启动的请求以及预期的响应。用于标识路径项对象的键值是一个在运行时评估的表达式，用于标识回调操作要使用的 URL。

要描述与另一个 API 调用无关的来自 API 提供者的传入请求，请使用 webhooks 字段。

模式化字段

字段模式	类型	描述
{表达式}	路径项对象	一个路径项对象，用于定义回调请求和预期响应。可提供完整示例。

此对象 MAY 使用规范扩展进行扩展。

关键表达式

标识路径项对象的键是一个运行时表达式，可以在运行时 HTTP 请求/响应的上下文中进行评估，以标识用于回调请求的 URL。一个简单的例子可能是 $request.body#/url。但是，使用运行时表达式可以访问完整的 HTTP 消息。这包括访问 JSON Pointer RFC6901 可以引用的正文的任何部分。

例如，给定以下 HTTP 请求

POST /subscribe/myevent?queryUrl=https://clientdomain.com/stillrunning HTTP/1.1
Host: example.org
Content-Type: application/json
Content-Length: 188

{
  "failedUrl": "https://clientdomain.com/failed",
  "successUrls": [
    "https://clientdomain.com/fast",
    "https://clientdomain.com/medium",
    "https://clientdomain.com/slow"
  ]
}

结果是

201 Created
Location: https://example.org/subscription/1

以下示例展示了各种表达式如何评估，假设回调操作有一个名为 eventType 的路径参数和一个名为 queryUrl 的查询参数。

表达式	值
$url	https://example.org/subscribe/myevent?queryUrl=https://clientdomain.com/stillrunning
$method	POST
$request.path.eventType	myevent
$request.query.queryUrl	https://clientdomain.com/stillrunning
$request.header.content-type	application/json
$request.body#/failedUrl	https://clientdomain.com/failed
$request.body#/successUrls/1	https://clientdomain.com/medium
$response.header.Location	https://example.org/subscription/1

回调对象示例

以下示例使用用户提供的 queryUrl 查询字符串参数来定义回调 URL。这类似于 webhook，但不同之处在于回调仅因发送 queryUrl 的初始请求而发生。

myCallback:
  '{$request.query.queryUrl}':
    post:
      requestBody:
        description: Callback payload
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SomePayload'
      responses:
        '200':
          description: callback successfully processed

以下示例展示了一个回调，其中服务器是硬编码的，但查询字符串参数是从请求体中的 id 和 email 属性填充的。

transactionCallback:
  'http://notificationServer.com?transactionId={$request.body#/id}&email={$request.body#/email}':
    post:
      requestBody:
        description: Callback payload
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SomePayload'
      responses:
        '200':
          description: callback successfully processed

示例对象

一个将内部或外部示例值与基本 summary 和 description 元数据分组的对象。此对象通常用于名为 examples（复数）的字段中，并且是较旧的 example（单数）字段的可引用替代方案，后者不支持引用或元数据。

示例允许演示 OpenAPI 中属性、参数和对象的使用。

固定字段

字段名称	类型	描述
摘要	`string`	示例的简短描述。
描述	`string`	示例的详细描述。可以使用 CommonMark 语法进行富文本表示。
值	任意	嵌入式字面量示例。`value` 字段和 `externalValue` 字段互斥。为了表示无法自然地在 JSON 或 YAML 中表示的媒体类型示例，请使用字符串值来包含示例，并在必要时进行转义。
外部值	`string`	标识字面量示例的 URI。这提供了引用无法轻松包含在 JSON 或 YAML 文档中的示例的能力。`value` 字段和 `externalValue` 字段互斥。请参阅解析相对引用的规则。

此对象 MAY 使用规范扩展进行扩展。

在所有情况下，示例值应与其关联值的模式兼容。工具实现可以选择自动验证兼容性，并在不兼容时拒绝示例值。

处理示例

示例对象可以在参数对象和媒体类型对象中使用。在这两个对象中，通过 examples（复数）字段完成。但是，还有其他几种提供示例的方法：在两个对象中与 examples 互斥的 example（单数）字段，以及出现在两个对象的 schema 字段中的模式对象中的两个关键字（已弃用的单数 example 和当前的复数 examples，它接受一个示例数组）。这些字段中的每一个都有略微不同的注意事项。

模式对象的字段用于显示示例值，而不考虑它们如何格式化为参数或媒体类型表示形式。examples 数组是 JSON Schema 的一部分，是模式对象中包含示例的首选方式，而 example 仅为与旧版 OpenAPI 规范兼容而保留。

参数或媒体类型对象中互斥的字段用于显示示例值，这些值应该既匹配模式，又应以其作为序列化参数或媒体类型表示形式中出现的方式进行格式化。确切的序列化和编码由参数对象中的各种字段或媒体类型对象的编码对象确定。由于使用这些字段的示例表示数据的最终序列化形式，因此它们应覆盖相应模式对象中的任何 example。

参数或媒体类型对象中的单数 example 字段对于简单示例来说简洁方便，但与使用 examples 下的示例对象相比，没有其他优势。

有些示例无法直接用 JSON 或 YAML 表示。对于所有三种提供示例的方式，这些示例都可以显示为字符串值，并进行任何必要的转义，以使字符串在构成 OpenAPI 描述的文档的 JSON 或 YAML 格式中有效。对于示例对象，此类值可以通过 externalValue 字段进行处理。

示例对象示例

在请求体中

requestBody:
  content:
    'application/json':
      schema:
        $ref: '#/components/schemas/Address'
      examples:
        foo:
          summary: A foo example
          value:
            foo: bar
        bar:
          summary: A bar example
          value:
            bar: baz
    application/xml:
      examples:
        xmlExample:
          summary: This is an example in XML
          externalValue: https://example.org/examples/address-example.xml
    text/plain:
      examples:
        textExample:
          summary: This is a text example
          externalValue: https://foo.bar/examples/address-example.txt

在参数中

parameters:
  - name: zipCode
    in: query
    schema:
      type: string
      format: zip-code
    examples:
      zip-example:
        $ref: '#/components/examples/zip-example'

在响应中

responses:
  '200':
    description: your car appointment has been booked
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/SuccessResponse'
        examples:
          confirmation-success:
            $ref: '#/components/examples/confirmation-success'

JSON 字符串的两种不同用法

首先，一个只是 JSON 字符串（而不是包含字符串的对象）的请求或响应体

"application/json": {
  "schema": {
    "type": "string"
  },
  "examples": {
    "jsonBody": {
      "description": "A body of just the JSON string \"json\"",
      "value": "json"
    }
  }
}

application/json:
  schema:
    type: string
  examples:
    jsonBody:
      description: 'A body of just the JSON string "json"'
      value: json

在上面的例子中，我们可以直接显示 JSON 字符串（或任何 JSON 值），而不是将序列化的 JSON 值塞进一个 JSON 字符串，那看起来会像 "\"json\""。

相比之下，一个编码在 URL 风格表单体内的 JSON 字符串

"application/x-www-form-urlencoded": {
  "schema": {
    "type": "object",
    "properties": {
      "jsonValue": {
        "type": "string"
      }
    }
  },
  "encoding": {
    "jsonValue": {
      "contentType": "application/json"
    }
  },
  "examples": {
    "jsonFormValue": {
      "description": "The JSON string \"json\" as a form value",
      "value": "jsonValue=%22json%22"
    }
  }
}

application/x-www-form-urlencoded:
  schema:
    type: object
    properties:
      jsonValue:
        type: string
  encoding:
    jsonValue:
      contentType: application/json
  examples:
    jsonFormValue:
      description: 'The JSON string "json" as a form value'
      value: jsonValue=%22json%22

在此示例中，JSON 字符串在编码成 URL 表单值之前必须进行序列化，因此示例中包含了 JSON 序列化中的引号，然后这些引号再进行 URL 百分比编码。

链接对象

链接对象表示响应可能的设计时链接。链接的存在不保证调用者能够成功调用它，而是提供响应与其他操作之间已知关系和遍历机制。

与动态链接（即响应载荷中提供的链接）不同，OAS 链接机制不需要运行时响应中的链接信息。

为了计算链接并提供执行它们的指令，使用运行时表达式来访问操作中的值，并将其用作参数来调用链接的操作。

固定字段

字段名称	类型	描述
operationRef	`string`	对 OAS 操作的 URI 引用。此字段与 `operationId` 字段互斥，并且必须指向一个操作对象。相对 `operationRef` 值可以用于定位 OpenAPI 描述中现有的操作对象。
operationId	`string`	现有、可解析的 OAS 操作的名称，通过唯一的 `operationId` 定义。此字段与 `operationRef` 字段互斥。
参数	映射[`string`, 任意 \| {表达式}]	一个映射，表示要传递给由 `operationId` 指定或通过 `operationRef` 标识的操作的参数。键是要使用的参数名称（可选地带参数位置限定符，例如路径中 `id` 参数的 `path.id`），而值可以是常量或要评估并传递给链接操作的表达式。
请求体	任意 \| {表达式}	调用目标操作时用作请求体的字面量值或{表达式}。
描述	`string`	链接的描述。可以使用 CommonMark 语法进行富文本表示。
服务器	服务器对象	目标操作要使用的服务器对象。

此对象 MAY 使用规范扩展进行扩展。

链接操作必须通过 operationRef 或 operationId 标识。标识或引用的操作必须是唯一的，并且在 operationId 的情况下，它必须在 OpenAPI 描述 (OAD) 的范围内解析。由于可能存在名称冲突，对于多文档 OAD，首选 operationRef 语法。但是，由于操作的使用依赖于路径对象中的 URL 路径模板，因此 OAD 中多次引用的任何路径项对象中的操作无法明确解析。在此类模糊情况下，结果行为是实现定义的，并且可能导致错误。

请注意，无法向 parameters 提供与运行时表达式语法匹配的常量值。可能会有模糊的参数名称，例如 name: "id", in: "path" 和 name: "path.id", in: "query"；这不建议使用，并且行为是实现定义的，但是实现应优先选择限定解释（path.id 作为路径参数），因为名称始终可以限定以消除歧义（例如，对于查询参数使用 query.path.id）。

示例

从请求操作计算链接，其中 $request.path.id 用于将请求参数传递给链接操作。

paths:
  /users/{id}:
    parameters:
      - name: id
        in: path
        required: true
        description: the user identifier, as userId
        schema:
          type: string
    get:
      responses:
        '200':
          description: the user being returned
          content:
            application/json:
              schema:
                type: object
                properties:
                  uuid: # the unique user id
                    type: string
                    format: uuid
          links:
            address:
              # the target link operationId
              operationId: getUserAddress
              parameters:
                # get the `id` field from the request path parameter named `id`
                userid: $request.path.id
  # the path item of the linked operation
  /users/{userid}/address:
    parameters:
      - name: userid
        in: path
        required: true
        description: the user identifier, as userId
        schema:
          type: string
    # linked operation
    get:
      operationId: getUserAddress
      responses:
        '200':
          description: the user's address

当运行时表达式评估失败时，不会将参数值传递给目标操作。

响应体中的值可用于驱动链接操作。

links:
  address:
    operationId: getUserAddressByUUID
    parameters:
      # get the `uuid` field from the `uuid` field in the response body
      userUuid: $response.body#/uuid

客户端自行决定是否跟随所有链接。链接的存在本身并不能保证调用者有权或有能力成功调用该链接。

`operationRef` 示例

由于对 operationId 的引用可能不可行（operationId 是操作对象中的可选字段），因此也可以通过相对 operationRef 进行引用

links:
  UserRepositories:
    # returns array of '#/components/schemas/repository'
    operationRef: '#/paths/~12.0~1repositories~1%7Busername%7D/get'
    parameters:
      username: $response.body#/username

或 URI operationRef

links:
  UserRepositories:
    # returns array of '#/components/schemas/repository'
    operationRef: https://na2.gigantic-server.com/#/paths/~12.0~1repositories~1%7Busername%7D/get
    parameters:
      username: $response.body#/username

请注意，在使用 operationRef 时，使用 JSON Pointer 时需要转义的正斜杠，并且在使用 JSON Pointer 作为 URI 片段时，需要将 { 和 } 分别进行 URL 编码，编码为 %7B 和 %7D。

运行时表达式

运行时表达式允许根据仅在实际 API 调用中的 HTTP 消息中可用的信息定义值。此机制由链接对象和回调对象使用。

运行时表达式由以下 ABNF 语法定义

    expression = "$url" / "$method" / "$statusCode" / "$request." source / "$response." source
    source     = header-reference / query-reference / path-reference / body-reference
    header-reference = "header." token
    query-reference  = "query." name
    path-reference   = "path." name
    body-reference   = "body" ["#" json-pointer ]
    json-pointer    = *( "/" reference-token )
    reference-token = *( unescaped / escaped )
    unescaped       = %x00-2E / %x30-7D / %x7F-10FFFF
                    ; %x2F ('/') and %x7E ('~') are excluded from 'unescaped'
    escaped         = "~" ( "0" / "1" )
                    ; representing '~' and '/', respectively
    name = *( CHAR )
    token = 1*tchar
    tchar = "!" / "#" / "$" / "%" / "&" / "'" / "*" / "+" / "-" / "."
          / "^" / "_" / "`" / "|" / "~" / DIGIT / ALPHA

在此，json-pointer 取自 RFC6901，char 取自 RFC7159，token 取自 RFC7230。

name 标识符区分大小写，而 token 不区分。

下表提供了运行时表达式的示例及其在值中的使用示例

示例

源位置	表达式示例	注释
HTTP 方法	`$method`	`$method` 的允许值将与 HTTP 操作的值相同。
请求的媒体类型	`$request.header.accept`
请求参数	`$request.path.id`	请求参数必须在父操作的 `parameters` 部分中声明，否则无法进行评估。这包括请求头部。
请求体属性	`$request.body#/user/uuid`	在接受有效载荷的操作中，可以引用 `requestBody` 的部分或整个正文。
请求 URL	`$url`
响应值	`$response.body#/status`	在返回有效载荷的操作中，可以引用响应体的部分或整个正文。
响应头部	`$response.header.Server`	仅提供单个头部值

运行时表达式保留被引用值的类型。表达式可以通过用 {} 花括号括起来嵌入到字符串值中。

头部对象

描述 HTTP 响应和 multipart 表示中的各个部分的单个头部；有关哪些头部可以描述的限制，请参阅相关的响应对象和编码对象文档。

头部对象遵循参数对象的结构，包括根据 schema 或 content 是否存在来确定其序列化策略，并进行以下更改

不得指定 name，它在相应的 headers 映射中给出。
不得指定 in，它隐式地在 header 中。
所有受位置影响的特性必须适用于 header 位置（例如，style）。这意味着不得使用 allowEmptyValue 和 allowReserved，并且 style（如果使用）必须限于 "simple"。

固定字段

常用固定字段

这些字段 MAY 与 content 或 schema 一起使用。

字段名称	类型	描述
描述	`string`	对头部的简要描述。这可以包含使用示例。可以使用 CommonMark 语法进行富文本表示。
必需	`布尔值`	确定此头部是否强制。默认值为 `false`。
已弃用	`布尔值`	指定头部已弃用，应逐步淘汰使用。默认值为 `false`。

此对象 MAY 使用规范扩展进行扩展。

与 `schema` 一起使用的固定字段

对于更简单的场景，schema 和 style 可以描述头部的结构和语法。当 example 或 examples 与 schema 字段一起提供时，示例必须遵循头部规定的序列化策略。

对于值中包含参数（名称=值对，后跟 ;）或值可能包含非 URL 安全字符的头部，不建议使用 schema 进行序列化；详见附录 D。

当 example 或 examples 与 schema 字段一起提供时，示例应与指定的模式匹配，并遵循头部规定的序列化策略。example 和 examples 字段互斥，如果其中任何一个存在，它将覆盖模式中的任何 example。

字段名称	类型	描述
style	`string`	描述头部值将如何序列化。默认值（也是头部的唯一合法值）为 `"simple"`。
explode	`布尔值`	当此值为 true 时，`array` 或 `object` 类型的头部值将生成一个单一头部，其值是数组项或映射键值对的逗号分隔列表，请参阅样式示例。对于其他数据类型，此字段无效。默认值为 `false`。
模式	模式对象 \| 引用对象	定义头部所用类型的模式。
示例	任意	头部潜在值的示例；请参阅处理示例。
示例	Map[ `string`, 示例对象 \| 引用对象]	头部潜在值的示例；请参阅处理示例。

另请参阅附录 C：使用基于 RFC6570 的序列化以获取额外指导。

与 `content` 一起使用的固定字段

对于更复杂的场景，content 字段可以定义头部的媒体类型和模式，并给出其使用示例。对于 schema 策略不适用的头部，建议使用 content 和 text/plain 媒体类型。

字段名称	类型	描述
内容	Map[`string`, 媒体类型对象]	一个包含头部表示的映射。键是媒体类型，值描述了它。该映射只能包含一个条目。

头部对象示例

一个简单的 integer 类型头部

"X-Rate-Limit-Limit": {
  "description": "The number of allowed requests in the current period",
  "schema": {
    "type": "integer"
  }
}

X-Rate-Limit-Limit:
  description: The number of allowed requests in the current period
  schema:
    type: integer

要求存在一个强 ETag 头部（值以 " 而不是 W/ 开头）。请注意 content 的使用，因为使用 schema 和 style 将要求 " 被百分比编码为 %22

"ETag": {
  "required": true,
  "content": {
    "text/plain": {
      "schema": {
        "type": "string",
        "pattern": "^\""
      }
    }
  }
}

ETag:
  required: true
  content:
    text/plain:
      schema:
        type: string
        pattern: ^"

标签对象

为操作对象使用的单个标签添加元数据。不强制要求每个在操作对象实例中定义的标签都有一个标签对象。

固定字段

字段名称	类型	描述
名称	`string`	必需。标签的名称。
描述	`string`	标签的描述。可以使用 CommonMark 语法进行富文本表示。
externalDocs	外部文档对象	此标签的额外外部文档。

此对象 MAY 使用规范扩展进行扩展。

标签对象示例

{
  "name": "pet",
  "description": "Pets operations"
}

name: pet
description: Pets operations

引用对象

一个简单的对象，允许在 OpenAPI 描述中引用其他组件，包括内部和外部引用。

$ref 字符串值包含一个 URI RFC3986，它标识被引用的值。

请参阅解析相对引用的规则。

固定字段

字段名称	类型	描述
$ref	`string`	必需。引用标识符。这必须是 URI 形式。
摘要	`string`	一个简短的摘要，默认情况下应覆盖被引用组件的摘要。如果被引用对象类型不允许 `summary` 字段，则此字段无效。
描述	`string`	一个描述，默认情况下应覆盖被引用组件的描述。可以使用 CommonMark 语法进行富文本表示。如果被引用对象类型不允许 `description` 字段，则此字段无效。

此对象不能用附加属性扩展，任何附加属性都应被忽略。

请注意，此附加属性的限制是引用对象与包含 $ref 关键字的模式对象之间的区别。

引用对象示例

{
  "$ref": "#/components/schemas/Pet"
}

$ref: '#/components/schemas/Pet'

相对模式文档示例

{
  "$ref": "Pet.json"
}

$ref: Pet.yaml

带嵌入式模式的相对文档示例

{
  "$ref": "definitions.json#/Pet"
}

$ref: definitions.yaml#/Pet

Schema 对象

模式对象允许定义输入和输出数据类型。这些类型可以是对象，也可以是原始类型和数组。此对象是 JSON Schema Specification Draft 2020-12 的超集。空模式（允许任何实例验证）可以由布尔值 true 表示，而不允许任何实例验证的模式可以由布尔值 false 表示。

有关关键字的更多信息，请参阅JSON Schema Core 和 JSON Schema Validation。

除非另有说明，关键字定义遵循 JSON Schema 的定义，并且不添加任何额外的语义；这包括 $schema、$id、$ref 和 $dynamicRef 等关键字是 URI 而不是 URL。如果 JSON Schema 指出行为由应用程序定义（例如，对于注释），则 OAS 也将语义定义推迟到使用 OpenAPI 文档的应用程序。

JSON Schema 关键字

OpenAPI 模式对象方言被定义为要求OAS 基本词汇表，此外还要求 JSON Schema Specification Draft 2020-12 通用元模式中指定的词汇表。

此规范版本的 OpenAPI 模式对象方言由 URI https://spec.openapis.org.cn/oas/3.1/dialect/base（“OAS 方言模式 ID”）标识。

以下关键字取自 JSON Schema 规范，但其定义已由 OAS 扩展

描述 - 可以使用 CommonMark 语法进行富文本表示。
格式 - 更多详情请参阅数据类型格式。虽然依赖 JSON Schema 定义的格式，但 OAS 提供了一些额外的预定义格式。

除了构成 OAS 方言的 JSON Schema 关键字外，模式对象还支持来自任何其他词汇表或完全任意属性的关键字。

JSON Schema 实现可以选择将 OpenAPI 规范基本词汇表定义的关键字视为未知关键字，因为其包含在 OAS 方言中，且 $vocabulary 值为 false。OAS 基本词汇表由以下关键字组成

固定字段

字段名称	类型	描述
鉴别器	鉴别器对象	添加对多态性的支持。鉴别器用于确定有效载荷预期满足哪一组模式。有关更多详细信息，请参阅组合和继承。
xml	XML 对象	此字段只能用于属性模式。它对根模式无效。添加额外的元数据来描述此属性的 XML 表示。
externalDocs	外部文档对象	此模式的额外外部文档。
示例	任意	一个自由格式字段，用于包含此模式实例的示例。为了表示无法自然地在 JSON 或 YAML 中表示的示例，可以使用字符串值来包含示例，并在必要时进行转义。已弃用： `example` 字段已被弃用，取而代之的是 JSON Schema `examples` 关键字。不鼓励使用 `example`，本规范的后续版本可能会将其删除。

此对象可以使用规范扩展进行扩展，但如前所述，在此对象内，附加属性可以省略 x- 前缀。

带注解的扩展验证

JSON Schema Draft 2020-12 支持收集注解，包括将未识别的关键字视为注解。OAS 实现可以使用此类注解，包括未被识别为声明的 JSON Schema 词汇表一部分的扩展，作为进一步验证的基础。请注意，JSON Schema Draft 2020-12 不要求扩展带有 x- 前缀。

非验证约束关键字

format 关键字（当使用默认格式注解词汇表时）和contentMediaType、contentEncoding 和 contentSchema 关键字定义了数据约束，但被视为注解而不是直接验证。扩展验证是强制执行这些约束的一种方式。

验证 `readOnly` 和 `writeOnly`

readOnly 和 writeOnly 关键字是注释，因为 JSON Schema 不知道它正在验证的数据是如何使用的。这些关键字的验证可以通过检查注释、读写方向和（如果相关）字段的当前值来完成。JSON Schema Validation Draft 2020-12 §9.4 定义了这些关键字的预期行为，包括资源（描述为“拥有者权限”）可以忽略 readOnly 字段或将其视为错误。

同时必需且只读的字段是一个示例，说明在 PUT 请求中忽略 readOnly: true 约束何时有益，特别是如果值未更改。这允许在 GET 请求中正确要求该字段，并且仍使用相同的表示和模式进行 PUT 请求。即使只读字段不是必需的，剥离它们对客户端来说也是繁重的，特别是当 JSON 数据复杂或嵌套很深时。

请注意，特别是 readOnly 的行为与本规范 3.0 版本中指定的行为不同。

数据建模技术

组合和继承（多态性）

OpenAPI 规范允许使用 JSON Schema 的 allOf 关键字组合和扩展模型定义，从而实现模型组合。allOf 接受一个对象定义数组，这些定义是独立验证的，但共同构成一个单一对象。

虽然组合提供了模型可扩展性，但它并不意味着模型之间存在层次结构。为了支持多态性，OpenAPI 规范添加了discriminator字段。使用时，discriminator 指示属性的名称，该属性提示哪个模式定义预期验证模型的结构。因此，discriminator 字段必须是必需字段。有两种方法可以为继承实例定义鉴别器的值。

使用模式名称。
通过使用新值覆盖属性来覆盖模式名称。如果存在新值，则其优先于模式名称。

通用（模板）数据结构

实现可以支持使用 JSON Schema 的动态引用特性定义通用或模板数据结构

$dynamicAnchor 标识一组可能的模式（包括一个默认占位符模式），$dynamicRef 可以解析到这些模式
$dynamicRef 解析到从模式入口点到引用路径上遇到的第一个匹配的 $dynamicAnchor，如 JSON Schema 规范中所述

“模式对象示例”部分包含一个示例，更多信息可在 Learn OpenAPI 网站的“动态引用”页面找到。

带注解的枚举

模式对象的 enum 关键字不允许将描述或其他信息与单个值关联。

实现可以支持识别 oneOf 或 anyOf，其中关键字数组中的每个子模式都包含一个 const 关键字和诸如 title 或 description 之类的注释，作为带有附加信息的枚举类型。此模式的具体行为超出 JSON Schema 要求的部分是实现定义的。

XML 建模

xml 字段允许在将 JSON 定义转换为 XML 时进行额外定义。XML 对象包含有关可用选项的附加信息。

指定模式方言

对于工具来说，能够确定任何给定资源希望使用哪种方言或元模式进行处理非常重要：JSON Schema Core、JSON Schema Validation、OpenAPI Schema 方言，或某些自定义元模式。

$schema 关键字可以出现在作为模式资源根的任何模式对象中，如果存在，则必须用于确定处理模式时应使用的方言。这允许使用符合 JSON Schema 其他草案（而非默认的 Draft 2020-12 支持）的模式对象。工具必须支持OAS 方言模式 ID，并且可以支持 $schema 的其他值。

为了允许在 OAS 文档中包含的所有模式对象使用不同的默认 $schema 值，可以在OpenAPI 对象中设置 jsonSchemaDialect 值。如果未设置此默认值，则这些模式对象必须使用 OAS 方言模式 ID。资源根模式对象中的 $schema 值始终覆盖任何默认值。

对于未设置 $schema 的独立 JSON Schema 文档，或对于 OpenAPI 描述文档中不是完整文档的模式对象，应假定方言为 OAS 方言。但是，为了最大限度地提高互操作性，建议 OpenAPI 描述作者在此类文档中通过 $schema 明确设置方言。

模式对象示例

原始类型示例

{
  "type": "string",
  "format": "email"
}

type: string
format: email

简单模型

{
  "type": "object",
  "required": ["name"],
  "properties": {
    "name": {
      "type": "string"
    },
    "address": {
      "$ref": "#/components/schemas/Address"
    },
    "age": {
      "type": "integer",
      "format": "int32",
      "minimum": 0
    }
  }
}

type: object
required:
  - name
properties:
  name:
    type: string
  address:
    $ref: '#/components/schemas/Address'
  age:
    type: integer
    format: int32
    minimum: 0

带映射/字典属性的模型

对于简单的字符串到字符串映射

{
  "type": "object",
  "additionalProperties": {
    "type": "string"
  }
}

type: object
additionalProperties:
  type: string

对于字符串到模型映射

{
  "type": "object",
  "additionalProperties": {
    "$ref": "#/components/schemas/ComplexModel"
  }
}

type: object
additionalProperties:
  $ref: '#/components/schemas/ComplexModel'

带有注解枚举的模型

{
  "oneOf": [
    {
      "const": "RGB",
      "title": "Red, Green, Blue",
      "description": "Specify colors with the red, green, and blue additive color model"
    },
    {
      "const": "CMYK",
      "title": "Cyan, Magenta, Yellow, Black",
      "description": "Specify colors with the cyan, magenta, yellow, and black subtractive color model"
    }
  ]
}

oneOf:
  - const: RGB
    title: Red, Green, Blue
    description: Specify colors with the red, green, and blue additive color model
  - const: CMYK
    title: Cyan, Magenta, Yellow, Black
    description: Specify colors with the cyan, magenta, yellow, and black subtractive color model

带示例的模型

{
  "type": "object",
  "properties": {
    "id": {
      "type": "integer",
      "format": "int64"
    },
    "name": {
      "type": "string"
    }
  },
  "required": ["name"],
  "examples": [
    {
      "name": "Puma",
      "id": 1
    }
  ]
}

type: object
properties:
  id:
    type: integer
    format: int64
  name:
    type: string
required:
  - name
examples:
  - name: Puma
    id: 1

带组合的模型

{
  "components": {
    "schemas": {
      "ErrorModel": {
        "type": "object",
        "required": ["message", "code"],
        "properties": {
          "message": {
            "type": "string"
          },
          "code": {
            "type": "integer",
            "minimum": 100,
            "maximum": 600
          }
        }
      },
      "ExtendedErrorModel": {
        "allOf": [
          {
            "$ref": "#/components/schemas/ErrorModel"
          },
          {
            "type": "object",
            "required": ["rootCause"],
            "properties": {
              "rootCause": {
                "type": "string"
              }
            }
          }
        ]
      }
    }
  }
}

components:
  schemas:
    ErrorModel:
      type: object
      required:
        - message
        - code
      properties:
        message:
          type: string
        code:
          type: integer
          minimum: 100
          maximum: 600
    ExtendedErrorModel:
      allOf:
        - $ref: '#/components/schemas/ErrorModel'
        - type: object
          required:
            - rootCause
          properties:
            rootCause:
              type: string

支持多态性的模型

{
  "components": {
    "schemas": {
      "Pet": {
        "type": "object",
        "discriminator": {
          "propertyName": "petType"
        },
        "properties": {
          "name": {
            "type": "string"
          },
          "petType": {
            "type": "string"
          }
        },
        "required": ["name", "petType"]
      },
      "Cat": {
        "description": "A representation of a cat. Note that `Cat` will be used as the discriminating value.",
        "allOf": [
          {
            "$ref": "#/components/schemas/Pet"
          },
          {
            "type": "object",
            "properties": {
              "huntingSkill": {
                "type": "string",
                "description": "The measured skill for hunting",
                "default": "lazy",
                "enum": ["clueless", "lazy", "adventurous", "aggressive"]
              }
            },
            "required": ["huntingSkill"]
          }
        ]
      },
      "Dog": {
        "description": "A representation of a dog. Note that `Dog` will be used as the discriminating value.",
        "allOf": [
          {
            "$ref": "#/components/schemas/Pet"
          },
          {
            "type": "object",
            "properties": {
              "packSize": {
                "type": "integer",
                "format": "int32",
                "description": "the size of the pack the dog is from",
                "default": 0,
                "minimum": 0
              }
            },
            "required": ["packSize"]
          }
        ]
      }
    }
  }
}

components:
  schemas:
    Pet:
      type: object
      discriminator:
        propertyName: petType
      properties:
        name:
          type: string
        petType:
          type: string
      required:
        - name
        - petType
    Cat: # "Cat" will be used as the discriminating value
      description: A representation of a cat
      allOf:
        - $ref: '#/components/schemas/Pet'
        - type: object
          properties:
            huntingSkill:
              type: string
              description: The measured skill for hunting
              enum:
                - clueless
                - lazy
                - adventurous
                - aggressive
          required:
            - huntingSkill
    Dog: # "Dog" will be used as the discriminating value
      description: A representation of a dog
      allOf:
        - $ref: '#/components/schemas/Pet'
        - type: object
          properties:
            packSize:
              type: integer
              format: int32
              description: the size of the pack the dog is from
              default: 0
              minimum: 0
          required:
            - packSize

通用数据结构模型

{
  "components": {
    "schemas": {
      "genericArrayComponent": {
        "$id": "fully_generic_array",
        "type": "array",
        "items": {
          "$dynamicRef": "#generic-array"
        },
        "$defs": {
          "allowAll": {
            "$dynamicAnchor": "generic-array"
          }
        }
      },
      "numberArray": {
        "$id": "array_of_numbers",
        "$ref": "fully_generic_array",
        "$defs": {
          "numbersOnly": {
            "$dynamicAnchor": "generic-array",
            "type": "number"
          }
        }
      },
      "stringArray": {
        "$id": "array_of_strings",
        "$ref": "fully_generic_array",
        "$defs": {
          "stringsOnly": {
            "$dynamicAnchor": "generic-array",
            "type": "string"
          }
        }
      },
      "objWithTypedArray": {
        "$id": "obj_with_typed_array",
        "type": "object",
        "required": ["dataType", "data"],
        "properties": {
          "dataType": {
            "enum": ["string", "number"]
          }
        },
        "oneOf": [{
          "properties": {
            "dataType": {"const": "string"},
            "data": {"$ref": "array_of_strings"}
          }
        }, {
          "properties": {
            "dataType": {"const": "number"},
            "data": {"$ref": "array_of_numbers"}
          }
        }]
      }
    }
  }
}

components:
  schemas:
    genericArrayComponent:
      $id: fully_generic_array
      type: array
      items:
        $dynamicRef: '#generic-array'
      $defs:
        allowAll:
          $dynamicAnchor: generic-array
    numberArray:
      $id: array_of_numbers
      $ref: fully_generic_array
      $defs:
        numbersOnly:
          $dynamicAnchor: generic-array
          type: number
    stringArray:
      $id: array_of_strings
      $ref: fully_generic_array
      $defs:
        stringsOnly:
          $dynamicAnchor: generic-array
          type: string
    objWithTypedArray:
      $id: obj_with_typed_array
      type: object
      required:
      - dataType
      - data
      properties:
        dataType:
          enum:
          - string
          - number
      oneOf:
      - properties:
          dataType:
            const: string
          data:
            $ref: array_of_strings
      - properties:
          dataType:
            const: number
          data:
            $ref: array_of_numbers

鉴别器对象

当请求体或响应载荷可能是多种不同模式之一时，鉴别器对象会提示文档的预期模式。此提示可用于辅助序列化、反序列化和验证。鉴别器对象通过隐式或显式地将命名属性的可能值与替代模式关联来实现这一点。

请注意，discriminator 不得更改模式的验证结果。

固定字段

字段名称	类型	描述
属性名称	`string`	必需。有效载荷中将包含鉴别值的属性名称。此属性在有效载荷模式中应为必需项，因为属性缺失时的行为是未定义的。
映射	映射[`string`, `string`]	一个用于保存有效载荷值与模式名称或 URI 引用之间映射的对象。

此对象 MAY 使用规范扩展进行扩展。

使用鉴别器对象的条件

鉴别器对象仅在使用复合关键字 oneOf、anyOf、allOf 之一时合法。

在 oneOf 和 anyOf 的用例中，当这些关键字与 discriminator 相邻时，所有可能的模式都必须明确列出。

为避免冗余，鉴别器可以添加到父模式定义中，并且所有通过 allOf 构造构建在父模式上的模式都可以用作备用模式。

discriminator 的 allOf 形式仅对非验证用例有用；使用此形式的 discriminator 对父模式进行验证不会搜索子模式或以任何方式在验证中使用它们。这是因为 discriminator 不能改变验证结果，并且没有标准 JSON Schema 关键字将父模式连接到子模式。

任何未在上面描述的 oneOf、anyOf、allOf 和 discriminator 配置的行为都是未定义的。

将值映射到模式的选项

propertyName 中命名的属性的值用作组件对象下关联模式的名称，除非该值存在 mapping。mapping 条目将特定属性值映射到不同的模式组件名称或由 URI 标识的模式。使用隐式或显式模式组件名称时，不考虑内联 oneOf 或 anyOf 子模式。既是有效模式名称又是有效相对 URI 引用的 mapping 值的行为是实现定义的，但建议将其视为模式名称。为确保所有实现都将模糊值（例如 "foo"）视为相对 URI 引用，作者必须以 "." 路径段作为前缀（例如 "./foo"）。

映射键必须是字符串值，但工具可以转换响应值以进行比较。但是，此类转换的具体性质是实现定义的。

示例

对于这些示例，假设所有模式都位于 OAD 的入口文档中；有关引用文档中 discriminator 的处理，请参阅解析隐式连接。

在 OAS 3.x 中，响应载荷可以被描述为多种类型中的精确一种

MyResponseType:
  oneOf:
    - $ref: '#/components/schemas/Cat'
    - $ref: '#/components/schemas/Dog'
    - $ref: '#/components/schemas/Lizard'

这意味着有效载荷必须通过验证，精确匹配 Cat、Dog 或 Lizard 所描述的模式之一。反序列化 oneOf 可能是一个耗费资源的操作，因为它需要确定哪个模式与有效载荷匹配，从而应该用于反序列化。这个问题也存在于 anyOf 模式中。discriminator 可以用作“提示”，以提高匹配模式选择的效率。discriminator 字段不能改变 oneOf 的验证结果，它只能帮助提高反序列化的效率并提供更好的错误消息。我们可以指定精确的字段，告诉我们预期哪个模式匹配实例

MyResponseType:
  oneOf:
    - $ref: '#/components/schemas/Cat'
    - $ref: '#/components/schemas/Dog'
    - $ref: '#/components/schemas/Lizard'
  discriminator:
    propertyName: petType

现在的预期是响应载荷中必须存在一个名为 petType 的属性，并且该值将与 OpenAPI 描述中定义的模式名称相对应。因此，响应载荷

{
  "id": 12345,
  "petType": "Cat"
}

将指示 Cat 模式预期与此载荷匹配。

在 discriminator 字段的值与模式名称不匹配或无法进行隐式映射的情况下，可以使用可选的 mapping 定义

MyResponseType:
  oneOf:
    - $ref: '#/components/schemas/Cat'
    - $ref: '#/components/schemas/Dog'
    - $ref: '#/components/schemas/Lizard'
    - $ref: https://gigantic-server.com/schemas/Monster/schema.json
  discriminator:
    propertyName: petType
    mapping:
      dog: '#/components/schemas/Dog'
      monster: https://gigantic-server.com/schemas/Monster/schema.json

这里的鉴别值 dog 将映射到模式 #/components/schemas/Dog，而不是默认（隐式）值 #/components/schemas/dog。如果鉴别值与隐式或显式映射不匹配，则无法确定模式，并且验证应失败。

当与 anyOf 构造结合使用时，使用鉴别器可以避免序列化器/反序列化器中因多个模式可能满足单个有效载荷而产生的歧义。

此示例展示了 allOf 的用法，这避免了在父级中引用所有子模式的需要

components:
  schemas:
    Pet:
      type: object
      required:
        - petType
      properties:
        petType:
          type: string
      discriminator:
        propertyName: petType
        mapping:
          dog: Dog
    Cat:
      allOf:
        - $ref: '#/components/schemas/Pet'
        - type: object
          # all other properties specific to a `Cat`
          properties:
            name:
              type: string
    Dog:
      allOf:
        - $ref: '#/components/schemas/Pet'
        - type: object
          # all other properties specific to a `Dog`
          properties:
            bark:
              type: string
    Lizard:
      allOf:
        - $ref: '#/components/schemas/Pet'
        - type: object
          # all other properties specific to a `Lizard`
          properties:
            lovesRocks:
              type: boolean

根据 Pet 模式验证，这样的载荷

{
  "petType": "Cat",
  "name": "Misty"
}

将指示 #/components/schemas/Cat 模式预期匹配。同样，此载荷

{
  "petType": "dog",
  "bark": "soft"
}

将映射到 #/components/schemas/Dog，因为 mapping 元素中的 dog 条目映射到 Dog，它是 #/components/schemas/Dog 的模式名称。

XML 对象

一个元数据对象，允许更精细的 XML 模型定义。

使用数组时，XML 元素名称不会被推断（对于单数/复数形式），并且应使用 name 字段添加该信息。有关预期行为，请参阅示例。

固定字段

字段名称	类型	描述
名称	`string`	替换用于所描述模式属性的元素/属性的名称。当在 `items` 中定义时，它将影响列表中单个 XML 元素的名称。当与 `type` 为 `"array"`（在 `items` 之外）一起定义时，它将影响包装元素，当且仅当 `wrapped` 为 `true` 时。如果 `wrapped` 为 `false`，它将被忽略。
命名空间	`string`	命名空间定义的 URI。值必须是非相对 URI 的形式。
前缀	`string`	用于名称的前缀。
属性	`布尔值`	声明属性定义是转换为属性而不是元素。默认值为 `false`。
wrapped	`布尔值`	仅可用于数组定义。表示数组是否被包装（例如，`<books><book/><book/></books>`）或不被包装（`<book/><book/>`）。默认值为 `false`。此定义仅在与 `type` 为 `"array"`（在 `items` 之外）一起定义时生效。

此对象 MAY 使用规范扩展进行扩展。

namespace 字段旨在匹配 XML 命名空间的语法，但也有一些注意事项

本规范的 3.1.0、3.0.3 及更早版本错误地使用了术语“绝对 URI”而不是“非相对 URI”，因此使用包含片段的命名空间的用户应仔细检查工具支持。
XML 允许但不鼓励使用相对 URI 引用，而本规范则明确禁止使用它们。
XML 1.1 允许 IRI (RFC3987) 作为命名空间，并规定命名空间在比较时无需任何编码或解码，这意味着为了满足本规范的 URI 语法要求而编码的 IRI 不能直接与 IRI 进行比较。

XML 对象示例

以下每个示例都表示 Schema 对象中因简洁性而省略的 properties 关键字的值。properties 值的 JSON 和 YAML 表示后面跟着为所示的单个属性生成的 XML 表示示例。

无 XML 元素

基本字符串属性

{
  "animals": {
    "type": "string"
  }
}

animals:
  type: string

<animals>...</animals>

基本字符串数组属性（wrapped 默认为 false）

{
  "animals": {
    "type": "array",
    "items": {
      "type": "string"
    }
  }
}

animals:
  type: array
  items:
    type: string

<animals>...</animals>
<animals>...</animals>
<animals>...</animals>

XML 名称替换

{
  "animals": {
    "type": "string",
    "xml": {
      "name": "animal"
    }
  }
}

animals:
  type: string
  xml:
    name: animal

<animal>...</animal>

XML 属性、前缀和命名空间

在此示例中，显示了完整的模型定义。

{
  "Person": {
    "type": "object",
    "properties": {
      "id": {
        "type": "integer",
        "format": "int32",
        "xml": {
          "attribute": true
        }
      },
      "name": {
        "type": "string",
        "xml": {
          "namespace": "https://example.com/schema/sample",
          "prefix": "sample"
        }
      }
    }
  }
}

Person:
  type: object
  properties:
    id:
      type: integer
      format: int32
      xml:
        attribute: true
    name:
      type: string
      xml:
        namespace: https://example.com/schema/sample
        prefix: sample

<Person id="123">
    <sample:name xmlns:sample="https://example.com/schema/sample">example</sample:name>
</Person>

XML 数组

更改元素名称

{
  "animals": {
    "type": "array",
    "items": {
      "type": "string",
      "xml": {
        "name": "animal"
      }
    }
  }
}

animals:
  type: array
  items:
    type: string
    xml:
      name: animal

<animal>value</animal>
<animal>value</animal>

外部 name 字段对 XML 没有影响

{
  "animals": {
    "type": "array",
    "items": {
      "type": "string",
      "xml": {
        "name": "animal"
      }
    },
    "xml": {
      "name": "aliens"
    }
  }
}

animals:
  type: array
  items:
    type: string
    xml:
      name: animal
  xml:
    name: aliens

<animal>value</animal>
<animal>value</animal>

即使数组被包装，如果未明确定义名称，内部和外部都将使用相同的名称

{
  "animals": {
    "type": "array",
    "items": {
      "type": "string"
    },
    "xml": {
      "wrapped": true
    }
  }
}

animals:
  type: array
  items:
    type: string
  xml:
    wrapped: true

<animals>
  <animals>value</animals>
  <animals>value</animals>
</animals>

为了克服上述示例中的命名问题，可以使用以下定义

{
  "animals": {
    "type": "array",
    "items": {
      "type": "string",
      "xml": {
        "name": "animal"
      }
    },
    "xml": {
      "wrapped": true
    }
  }
}

animals:
  type: array
  items:
    type: string
    xml:
      name: animal
  xml:
    wrapped: true

<animals>
  <animal>value</animal>
  <animal>value</animal>
</animals>

影响内部和外部名称

{
  "animals": {
    "type": "array",
    "items": {
      "type": "string",
      "xml": {
        "name": "animal"
      }
    },
    "xml": {
      "name": "aliens",
      "wrapped": true
    }
  }
}

animals:
  type: array
  items:
    type: string
    xml:
      name: animal
  xml:
    name: aliens
    wrapped: true

<aliens>
  <animal>value</animal>
  <animal>value</animal>
</aliens>

如果我们更改外部元素而不更改内部元素

{
  "animals": {
    "type": "array",
    "items": {
      "type": "string"
    },
    "xml": {
      "name": "aliens",
      "wrapped": true
    }
  }
}

animals:
  type: array
  items:
    type: string
  xml:
    name: aliens
    wrapped: true

<aliens>
  <aliens>value</aliens>
  <aliens>value</aliens>
</aliens>

安全方案对象

定义可用于操作的安全方案。

支持的方案包括 HTTP 身份验证、API 密钥（作为请求头、Cookie 参数或查询参数）、双向 TLS（使用客户端证书）、RFC6749 中定义的 OAuth2 常见流程（隐式、密码、客户端凭据和授权码），以及 [[OpenID-Connect-Core]]。请注意，截至 2020 年，OAuth 2.0 安全最佳实践即将弃用隐式流程。大多数用例推荐使用带 PKCE 的授权码授予流程。

固定字段

字段名称	类型	适用于	描述
type	`string`	任意	必需。安全方案的类型。有效值为 `"apiKey"`、`"http"`、`"mutualTLS"`、`"oauth2"`、`"openIdConnect"`。
description	`string`	任意	安全方案的描述。CommonMark 语法可用于富文本表示。
name	`string`	`apiKey`	必需。要使用的请求头、查询或 Cookie 参数的名称。
in	`string`	`apiKey`	必需。API 密钥的位置。有效值为 `"query"`、`"header"` 或 `"cookie"`。
scheme	`string`	`http`	必需。根据 RFC7235 定义，在 Authorization 请求头中使用的 HTTP 身份验证方案的名称。所使用的值应在 IANA 身份验证方案注册表中注册。该值不区分大小写，如 RFC7235 中所定义。
bearerFormat	`string`	`http` (`"bearer"`)	提示客户端如何格式化不记名令牌。不记名令牌通常由授权服务器生成，因此此信息主要用于文档目的。
flows	OAuth 流程对象	`oauth2`	必需。一个包含受支持流程类型的配置信息的对象。
openIdConnectUrl	`string`	`openIdConnect`	必需。众所周知 URL，用于发现 [[OpenID-Connect-Discovery]] 提供者元数据。

此对象 MAY 使用规范扩展进行扩展。

安全方案对象示例

基本身份验证示例

{
  "type": "http",
  "scheme": "basic"
}

type: http
scheme: basic

API 密钥示例

{
  "type": "apiKey",
  "name": "api-key",
  "in": "header"
}

type: apiKey
name: api-key
in: header

JWT 不记名令牌示例

{
  "type": "http",
  "scheme": "bearer",
  "bearerFormat": "JWT"
}

type: http
scheme: bearer
bearerFormat: JWT

双向 TLS 示例

{
  "type": "mutualTLS",
  "description": "Cert must be signed by example.com CA"
}

type: mutualTLS
description: Cert must be signed by example.com CA

OAuth2 隐式流程示例

{
  "type": "oauth2",
  "flows": {
    "implicit": {
      "authorizationUrl": "https://example.com/api/oauth/dialog",
      "scopes": {
        "write:pets": "modify pets in your account",
        "read:pets": "read your pets"
      }
    }
  }
}

type: oauth2
flows:
  implicit:
    authorizationUrl: https://example.com/api/oauth/dialog
    scopes:
      write:pets: modify pets in your account
      read:pets: read your pets

OAuth 流程对象

允许配置支持的 OAuth 流程。

固定字段

字段名称	类型	描述
implicit	OAuth 流程对象	OAuth 隐式流程的配置
password	OAuth 流程对象	OAuth 资源所有者密码流程的配置
clientCredentials	OAuth 流程对象	OAuth 客户端凭据流程的配置。在 OpenAPI 2.0 中曾被称为 `application`。
authorizationCode	OAuth 流程对象	OAuth 授权码流程的配置。在 OpenAPI 2.0 中曾被称为 `accessCode`。

此对象 MAY 使用规范扩展进行扩展。

OAuth 流程对象

支持的 OAuth 流程的配置详情

固定字段

字段名称	类型	适用于	描述
authorizationUrl	`string`	`oauth2` (`"implicit"`, `"authorizationCode"`)	必需。此流程要使用的授权 URL。这必须是 URL 形式。OAuth2 标准要求使用 TLS。
tokenUrl	`string`	`oauth2` (`"password"`, `"clientCredentials"`, `"authorizationCode"`)	必需。此流程要使用的令牌 URL。这必须是 URL 形式。OAuth2 标准要求使用 TLS。
refreshUrl	`string`	`oauth2`	用于获取刷新令牌的 URL。这必须是 URL 形式。OAuth2 标准要求使用 TLS。
scopes	映射[`string`, `string`]	`oauth2`	必需。OAuth2 安全方案的可用范围。范围名称与其简短描述之间的映射。该映射可以为空。

此对象 MAY 使用规范扩展进行扩展。

OAuth 流程对象示例

{
  "type": "oauth2",
  "flows": {
    "implicit": {
      "authorizationUrl": "https://example.com/api/oauth/dialog",
      "scopes": {
        "write:pets": "modify pets in your account",
        "read:pets": "read your pets"
      }
    },
    "authorizationCode": {
      "authorizationUrl": "https://example.com/api/oauth/dialog",
      "tokenUrl": "https://example.com/api/oauth/token",
      "scopes": {
        "write:pets": "modify pets in your account",
        "read:pets": "read your pets"
      }
    }
  }
}

type: oauth2
flows:
  implicit:
    authorizationUrl: https://example.com/api/oauth/dialog
    scopes:
      write:pets: modify pets in your account
      read:pets: read your pets
  authorizationCode:
    authorizationUrl: https://example.com/api/oauth/dialog
    tokenUrl: https://example.com/api/oauth/token
    scopes:
      write:pets: modify pets in your account
      read:pets: read your pets

安全要求对象

列出执行此操作所需的安全方案。每个属性使用的名称必须与 Components Object 下的 Security Schemes 中声明的安全方案相对应。

安全要求对象可以引用多个安全方案，在这种情况下，请求要获得授权，所有方案都必须满足。这使得需要多个查询参数或 HTTP 请求头来传递安全信息的场景成为可能。

当 OpenAPI 对象或 Operation 对象上定义了 security 字段并包含多个安全要求对象时，列表中只需满足其中一个条目即可授权请求。这使得 API 允许使用多个独立安全方案的场景成为可能。

空的安全要求对象（{}）表示支持匿名访问。

模式化字段

字段模式	类型	描述
{name}	[`string`]	每个名称都必须对应于 Components Object 下的 Security Schemes 中声明的安全方案。如果安全方案类型为 `"oauth2"` 或 `"openIdConnect"`，则值是执行所需的范围名称列表，如果授权不需要指定范围，则该列表可以为空。对于其他安全方案类型，该数组可以包含执行所需的角色名称列表，但这些名称未在其他地方定义或带内交换。

安全要求对象示例

另请参阅附录 F：在引用文档中解析安全要求，了解在多文档 OpenAPI 描述中使用安全要求对象的示例。

非 OAuth2 安全要求

{
  "api_key": []
}

api_key: []

OAuth2 安全要求

{
  "petstore_auth": ["write:pets", "read:pets"]
}

petstore_auth:
  - write:pets
  - read:pets

可选 OAuth2 安全

可选的 OAuth2 安全，如同在 OpenAPI 对象或 Operation 对象中定义的那样

{
  "security": [
    {},
    {
      "petstore_auth": ["write:pets", "read:pets"]
    }
  ]
}

security:
  - {}
  - petstore_auth:
      - write:pets
      - read:pets

规范扩展

尽管 OpenAPI 规范试图适应大多数用例，但仍可以在某些点添加额外数据以扩展规范。

扩展属性作为模式化字段实现，始终以 x- 为前缀。

字段模式	类型	描述
^x-	任意	允许对 OpenAPI Schema 进行扩展。字段名称必须以 `x-` 开头，例如 `x-internal-id`。以 `x-oai-` 和 `x-oas-` 开头的字段名称保留用于 OpenAPI Initiative 定义的用途。该值可以是任何有效的 JSON 值（`null`、基本类型、数组或对象）。

OpenAPI 倡议维护着多个 [[OpenAPI-Registry|扩展注册表]]，包括用于单个扩展关键字和扩展关键字命名空间的注册表。

扩展是证明规范拟议新增内容可行性的最佳方式之一。因此，建议在设计实现时考虑可扩展性，以支持社区实验。

对任何一个扩展的支持都是可选的，对一个扩展的支持不意味着对其他扩展的支持。

安全过滤

OpenAPI 规范中的某些对象可以声明并保持为空，或者完全移除，即使它们本质上是 API 文档的核心。

这样做的原因是为了允许对文档进行额外的访问控制层。虽然这不属于规范本身的一部分，但某些库可以选择根据某种形式的身份验证/授权来允许访问文档的某些部分。

两个示例

Paths Object 可以存在但为空。这可能有些反直觉，但它可能告诉查看者他们已到达正确位置，但无法访问任何文档。他们仍然至少可以访问 Info Object，其中可能包含有关身份验证的额外信息。
Path Item Object 可以为空。在这种情况下，查看者将知道路径存在，但无法看到其任何操作或参数。这与从 Paths Object 中隐藏路径本身不同，因为用户会知道它的存在。这允许文档提供者精细控制查看者可以看到的内容。

安全注意事项

OpenAPI 描述格式

OpenAPI 描述使用 JSON、YAML 和 JSON Schema 的组合，因此它们共享各自的安全注意事项

工具和使用场景

此外，OpenAPI 描述由各种工具处理，用于多种不同目的，例如客户端代码生成、文档生成、服务器端路由和 API 测试。OpenAPI 描述作者必须考虑 OpenAPI 描述可能使用的场景所带来的风险。

安全方案

OpenAPI 描述了用于保护其定义的资源的安全方案。可用的安全方案提供不同程度的保护。数据敏感性和安全漏洞的潜在影响等因素应指导 API 资源安全方案的选择。某些安全方案，例如基本身份验证和 OAuth 隐式流程，受支持是为了与现有 API 兼容。然而，它们包含在 OpenAPI 中并不意味着认可其使用，特别是对于高度敏感的数据或操作。

处理外部资源

OpenAPI 描述可能包含对外部资源的引用，这些资源可能由消费工具自动解引用。外部资源可能托管在不受信任的不同域上。

处理引用循环

OpenAPI 描述中的引用可能导致循环。工具必须检测并处理循环以防止资源耗尽。

Markdown 和 HTML 清理

某些字段允许使用 Markdown，其中可能包含 HTML（包括脚本）。工具的责任是适当地清理 Markdown。

附录 A：修订历史

版本	日期	注释
3.1.1	2024-10-24	OpenAPI 规范 3.1.1 的补丁版本
3.1.0	2021-02-15	OpenAPI 规范 3.1.0 发布
3.1.0-rc1	2020-10-08	3.1 规范的 rc1 版本
3.1.0-rc0	2020-06-18	3.1 规范的 rc0 版本
3.0.4	2024-10-24	OpenAPI 规范 3.0.4 的补丁版本
3.0.3	2020-02-20	OpenAPI 规范 3.0.3 的补丁版本
3.0.2	2018-10-08	OpenAPI 规范 3.0.2 的补丁版本
3.0.1	2017-12-06	OpenAPI 规范 3.0.1 的补丁版本
3.0.0	2017-07-26	OpenAPI 规范 3.0.0 发布
3.0.0-rc2	2017-06-16	3.0 规范的 rc2 版本
3.0.0-rc1	2017-04-27	3.0 规范的 rc1 版本
3.0.0-rc0	2017-02-28	3.0 规范的实施者草案
2.0	2015-12-31	将 Swagger 2.0 捐赠给 OpenAPI 倡议
2.0	2014-09-08	Swagger 2.0 发布
1.2	2014-03-14	正式文档的初始发布。
1.1	2012-08-22	Swagger 1.1 发布
1.0	2011-08-10	Swagger 规范首次发布

附录 B：数据类型转换

将类型化数据序列化为纯文本，这可能发生在 text/plain 消息体或 multipart 部分中，以及 URL 查询字符串或消息体中的 application/x-www-form-urlencoded 格式中，这涉及到重要的实现定义或应用程序定义的行为。

Schema 对象根据 JSON Schema 数据模型验证数据，该模型仅识别四种基本数据类型：字符串（仅作为 UTF-8 广泛互操作）、数字、布尔值和 null。值得注意的是，整数与其它数字不是不同的类型，type: "integer" 是一个数学上定义的便利，而不是基于任何字符串表示中是否存在小数点。

Parameter 对象、Header 对象和 Encoding 对象提供了控制如何排列数组或对象类型值的功能。它们还可以用于控制字符串如何进一步编码以避免保留字符或非法字符。然而，目前没有通用的规范来将经过 Schema 验证的非 UTF-8 基本数据类型（或整个数组或对象）转换为字符串。

有两种情况提供了基于标准的指导

RFC3987 为将非 Unicode 字符串转换为 UTF-8 提供了指导，特别是在 URI 的上下文中（以及通过扩展，使用相同编码规则的表单媒体类型）
RFC6570 指定了哪些值（包括但不限于 null）被视为 undefined，因此在基于该规范进行序列化时的扩展过程中会进行特殊处理

RFC6570 的实现通常有自己转换非字符串值的约定，但这些是实现特定的，并非由 RFC 本身定义。这是 OpenAPI 规范将这些转换作为实现定义的原因之一：它允许使用 RFC6570 实现，无论它们选择如何执行转换。

为了更精确地控制数字、布尔值和 null（或 RFC6570 认为未定义的其他值）的序列化，可以将 Schema 定义为 type: "string"，并使用 pattern、enum、format 和其他关键字进行约束，以说明应用程序在 Schema 验证之前必须如何预转换其数据。生成的字符串将不需要任何进一步的类型转换。

format 关键字可以辅助序列化。某些格式（如 date-time）是明确的，而其他格式（如格式注册表中的 decimal）则不太明确。然而，在使用 format 时必须小心，以确保所有相关工具都支持特定格式，因为无法识别的格式会被忽略。

要求输入预格式化、经过 Schema 验证的字符串也有助于提高往返互操作性，因为并非所有编程语言和环境都支持相同的数据类型。

附录 C：使用基于 RFC6570 的序列化

序列化在三种场景下根据 RFC6570 URI 模板定义

对象	条件
参数对象	当 `schema` 存在时
头部对象	当 `schema` 存在时
编码对象	当为 `application/x-www-form-urlencoded` 编码并使用了 `style`、`explode` 或 `allowReserved` 中的任何一个时

本规范的实现可以使用 RFC6570 的实现来执行变量扩展，但有一些注意事项。

请注意，当使用 style: "form" RFC6570 扩展来生成 application/x-www-form-urlencoded HTTP 消息体时，需要移除为满足 URI 查询字符串语法而生成的 ? 前缀。

当使用 style 和类似关键字生成 multipart/form-data 请求体时，查询字符串名称放在 Content-Disposition 部分请求头的 name 参数中，值放在相应的请求体部分中；不使用 ?、= 和 & 字符。请注意，虽然 RFC7578 允许在“文件名”中使用 [[RFC3986]] 百分号编码，但它没有另外说明在该格式内使用百分号编码的问题。RFC7578 详细讨论了 multipart/form-data 的字符集和编码问题，强烈建议 OpenAPI 描述作者在决定将基于 RFC6570 的序列化与此媒体类型一起使用之前仔细阅读此指导。

另请注意，并非所有 RFC6570 实现都支持所有四个级别的运算符，而 OpenAPI 规范的用法需要所有这些运算符才能完全支持。使用支持级别较低的实现将需要额外手动构建 URI 模板以解决这些限制。

字段与 RFC6570 运算符之间的等效性

某些字段值转换为 RFC6570 运算符（或缺乏运算符）

字段	值	等效
样式	`"simple"`	不适用
样式	`"matrix"`	`;` 前缀运算符
样式	`"label"`	`.` 前缀运算符
样式	`"form"`	`?` 前缀运算符
allowReserved	`false`	不适用
allowReserved	`true`	`+` 前缀运算符
展开	`false`	不适用
展开	`true`	`*` 修饰符后缀

多个 style: "form" 参数等同于使用 ? 前缀运算符的单个 RFC6570 变量列表

parameters:
- name: foo
  in: query
  schema:
    type: object
  explode: true
- name: bar
  in: query
  schema:
    type: string

此示例等效于 RFC6570 的 {?foo*,bar}，而**不是** {?foo*}{&bar}。后者有问题，因为如果 foo 未定义，结果将是一个无效的 URI。& 前缀运算符在 Parameter 对象中没有等效项。

请注意，RFC6570 没有指定超出 explode 处理的单一级别的复合值的行为。对于没有明确指定行为的对象或数组的使用结果是实现定义的。

参数值中的分隔符

RFC6570 扩展使用的分隔符，例如 style: "simple" 用于连接数组或对象值的 ,，只要 allowReserved 为 false，都会自动进行百分号编码。请注意，由于 RFC6570 没有定义基于 URI 模板解析变量的方法，因此用户必须注意先按分隔符分割值，然后才能对可能包含分隔符字符的值进行百分号解码。

当 allowReserved 为 true 时，百分号编码（在用分隔符连接值之前）和百分号解码（在分隔符上分割之后）都必须在正确的时间手动完成。

有关处理没有 RFC6570 等效项的 style 值的分隔符的更多指导（这些分隔符在用作分隔符时已经需要进行百分号编码），请参阅附录 E。

非 RFC6570 字段值和组合

没有直接 RFC6570 等效项的配置也应根据 RFC6570 处理。实现可以创建一个适当分隔的 URI 模板，其中包含用于单独名称和值的变量，并使用 RFC6570 常规或保留扩展（基于 allowReserved）。

这包括

pipeDelimited、spaceDelimited 和 deepObject 样式，它们根本没有等效项
样式 form 与 allowReserved: true 的组合，这是不允许的，因为一次只能使用一个前缀运算符
任何不是合法 RFC6570 变量名的参数名称

Parameter 对象的 name 字段比 RFC6570 变量名语法具有更宽松的语法。包含在允许的 RFC6570 变量字符集之外的字符的参数名称，在使用到 URI 模板之前必须进行百分号编码。

示例

假设我们想在表单查询字符串中使用以下数据，其中 formulas 是展开的，而 words 不是

formulas:
  a: x+y
  b: x/y
  c: x^y
words:
- math
- is
- fun

RFC6570 等效扩展

这个 Parameter 对象数组使用常规的 style: "form" 扩展，RFC6570 完全支持

parameters:
- name: formulas
  in: query
  schema:
    type: object
    additionalProperties:
      type: string
  explode: true
- name: words
  in: query
  schema:
    type: array
    items:
      type: string

这转换为以下 URI 模板

{?formulas*,words}

使用之前给定的数据扩展后，我们得到

?a=x%2By&b=x%2Fy&c=x%5Ey&words=math,is,fun

使用非 RFC6570 支持选项进行扩展

但是现在假设（出于某种原因），我们真的希望 b 公式中的 / 在查询字符串中原样显示，并且我们希望我们的单词像书面短语一样用空格分隔。为此，我们将 allowReserved: true 添加到 formulas，并将 words 的样式更改为 style: "spaceDelimited"

parameters:
- name: formulas
  in: query
  schema:
    type: object
    additionalProperties:
      type: string
  explode: true
  allowReserved: true
- name: words
  in: query
  style: spaceDelimited
  explode: false
  schema:
    type: array
    items:
      type: string

我们不能将 ? 和 + RFC6570 前缀结合使用，并且 RFC6570 无法将 , 分隔符替换为空格字符。因此，我们需要重构数据以适应手动构建的 URI 模板，该模板将所有部分通过正确的扩展类型。

这是这样一个模板，使用了一个虚构的约定：words.0 代表 words 值中的第一个条目，words.1 代表第二个，words.2 代表第三个

?a={+a}&b={+b}&c={+c}&words={words.0} {words.1} {words.2}

RFC6570 提到了使用 .“表示子结构中的名称层次结构”，但没有定义任何具体的命名约定或行为。由于 . 的使用不是自动的，我们需要为这个新模板构建一个合适的输入结构。

我们还需要预处理 formulas 的值，因为虽然 RFC3986 允许在查询字符串中使用 / 和大多数其他保留字符，但 [, ], 和 # 不允许，并且 &, =, 和 + 在 application/x-www-form-urlencoded 格式（即我们正在查询字符串中使用的格式）中都具有特殊行为。

设置 allowReserved: true *不会*使 URI 中不允许的保留字符变为允许，它只是允许它们*不变地通过扩展*。因此，任何工具仍然需要对这些字符进行百分号编码，因为保留扩展不会这样做，但它*会*保持百分号编码的三元组不变。另请参阅附录 E，了解有关百分号编码和表单媒体类型的进一步指导，包括关于在参数名称和值中处理 spaceDelimited、pipeDelimited 和 deepObject 的分隔符字符的指导。

因此，这是我们的数据结构，它将名称和值安排以适应上述模板，其中 formulas 的值已预先进行了 []#&=+ 的百分号编码（尽管本示例中只出现了 +）

a: x%2By
b: x/y
c: x^y
words.0: math
words.1: is
words.2: fun

使用我们重构的数据扩展我们手动组装的模板，得到以下查询字符串

?a=x%2By&b=x/y&c=x%5Ey&words=math%20is%20fun

/ 和预百分号编码的 %2B 未被处理，但不允许的 ^ 字符（值内部）和空格字符（在模板中但不在扩展变量内部）被百分号编码了。

未定义值和手动 URI 模板构建

手动构建模板时必须小心，以正确处理 RFC6570 视为 undefined 的值

formulas: {}
words:
- hello
- world

将此数据与我们原始的 RFC6570 兼容的 URI 模板 {?formulas*,words} 一起使用，会产生以下结果

?words=hello,world

这意味着手动构建的 URI 模板和重构的数据需要完全省略 formulas 对象，以便 words 参数成为查询字符串中的第一个也是唯一一个参数。

重构数据

words.0: hello
words.1: world

手动构建的 URI 模板

?words={words.0} {words.1}

结果

?words=hello%20world

非法变量名作为参数名

在此示例中，心形表情符号在 URI 模板名称（或 URI）中是不合法的

parameters:
- name: ❤️
  in: query
  schema:
    type: string

我们不能直接将 ❤️: "love!" 传递给 RFC6570 实现。相反，我们必须在数据和 URI 模板中都对名称（这是一个六八位组的 UTF-8 序列）进行预百分号编码。

"%E2%9D%A4%EF%B8%8F": love!

{?%E2%9D%A4%EF%B8%8F}

这将扩展为结果

?%E2%9D%A4%EF%B8%8F=love%21

附录 D：序列化请求头和 Cookie

RFC6570 的百分号编码行为并非总是适用于 in: "header" 和 in: "cookie" 参数。在许多情况下，更适合使用 content 和诸如 text/plain 这样的媒体类型，并要求应用程序组装正确的字符串。

对于使用 RFC8941 结构化字段语法的 RFC6265 Cookie 和 HTTP 请求头，非 ASCII 内容通过 base64 编码（contentEncoding: "base64"）处理。请注意，标准 base64 编码字母表包含非 URL 安全字符，这些字符在 RFC6570 扩展中会被百分号编码；因此不建议通过两种编码序列化值。虽然 contentEncoding 也支持 URL 安全的 base64url 编码，但请求头和 Cookie 的 RFC 中并未提及此编码。

大多数 HTTP 请求头早于结构化字段语法，对其语法和编码规则的全面评估超出了本规范的范围。虽然 RFC8187 建议对 HTTP（请求头或尾部）字段参数进行百分号编码，但这些参数出现在 ; 字符之后。如果使用 style: "simple"，该分隔符本身也将被百分号编码，从而违反了一般的 HTTP 字段语法。

对于单个值，将 style: "form" 与 in: "cookie" 结合使用是模糊的；对于多个值，则是不正确的。无论多个值是否是使用 explode: true 的结果，情况都如此。

这种样式被指定等同于包含 ? 字符的 RFC6570 表单扩展（详情请参阅附录 C），而 ? 字符并非 Cookie 语法的一部分。然而，本规范过往版本中的此类样式示例并未包含 ? 前缀，这表明这种比较并不精确。由于依赖 RFC6570 实现和基于样式示例执行自定义序列化的实现将产生不同的结果，因此这两种结果中哪种是正确的，由实现方自行决定。

对于多个值，style: "form" 总是错误的，因为 Cookie 中的 name=value 对以 ;（分号后跟一个空格字符）而不是 & 分隔。

附录 E：百分号编码和表单媒体类型

注意： 在本节中，为了可读性，application/x-www-form-urlencoded 和 multipart/form-data 媒体类型分别缩写为 form-urlencoded 和 form-data。

百分号编码用于 URI 以及从 URI 派生语法的媒体类型中。此过程涉及三组字符，它们的名称在不同规范中有所不同，但在本节中定义如下

非保留字符无需百分号编码；虽然对它们进行百分号编码是安全的，但这样做会生成一个未标准化的 URI
保留字符在 URI 语法中具有特殊行为（例如分隔组件），或者保留给其他需要定义特殊行为的规范（例如 form-urlencoded 为 =、& 和 + 定义了特殊行为）
不安全字符在某些环境中解析 URI 时已知会引起问题

除非另有规定，本节使用 RFC3986 对保留字符和非保留字符的定义，并将不安全字符集定义为不包含在这两组中的所有字符。

百分号编码和 `form-urlencoded`

每个 URI 组件（例如查询字符串）都认为某些保留字符不安全，原因要么是它们在组件之间充当分隔符（例如 #），要么是（对于 [ 和 ]）历史上被视为全局不安全，但后来出于有限目的被赋予了保留状态。

在组件内未定义特殊含义的保留字符可以不进行百分号编码。但是，其他规范可以定义特殊含义，要求对那些字符在额外特殊含义之外进行百分号编码。

form-urlencoded 媒体类型为 = 和 & 定义了作为分隔符的特殊含义，并为 + 定义了作为空格字符替代（而不是其百分号编码形式 %20）的特殊含义。这意味着，尽管这三个字符在 RFC3986 的查询字符串中是保留但允许的，但在 form-urlencoded 查询字符串中，它们必须进行百分号编码，除非它们用于 form-urlencoded 的特定目的；有关在表单值中处理 + 的示例，请参阅附录 C。

百分号编码和 `form-data`

RFC7578 建议使用基于 RFC3986 的百分号编码作为一种机制，以将基于文本的各部分请求头数据（如文件名）保持在 ASCII 字符集内。此建议并非 form-data 较旧（2015 年之前）规范的一部分，因此必须注意确保互操作性。

form-data 媒体类型允许在其部分中包含任意文本或二进制数据，因此不需要百分号编码，并且除非定义了部分的 Content-Type 要求，否则很可能导致互操作性问题。

生成和验证 URI 及 `form-urlencoded` 字符串

URI 百分号编码和 form-urlencoded 媒体类型具有复杂的规范历史，涵盖多个修订版，并且在某些情况下，不同标准机构之间存在相互冲突的所有权主张。不幸的是，这些规范各自定义了略微不同的百分号编码规则，如果 URI 或 form-urlencoded 消息体将受到严格验证，则需要考虑这些差异。（请注意，许多 URI 解析器默认不执行验证。）

本规范规范性地引用了以下相关标准

规范	日期	OAS 用法	百分号编码	注释
RFC3986	01/2005	URI/URL 语法	[[RFC3986]]	废弃 [[RFC1738]]，[[RFC2396]]
RFC6570	03/2012	基于样式的序列化	[[RFC3986]]	`form-urlencoded` 不使用 `+`
RFC1866	11/1995	基于内容的序列化	[[RFC1738]]	被 [[HTML401]] 第 17.13.4.1 节，[[URL]] 第 5 节废弃

当 schema 存在时，Parameter 对象中使用基于样式的序列化；当 style、explode 或 allowReserved 中至少有一个存在时，Encoding 对象中使用基于样式的序列化。有关 RFC6570 两种不同的百分号编码方法的更多详细信息，包括涉及 + 的示例，请参阅附录 C。

基于内容的序列化由 Media Type 对象定义，当 content 字段存在时与 Parameter 对象一起使用，当 style、explode 和 allowReserved 字段不存在时则与基于 contentType 字段的 Encoding 对象一起使用。每个部分都根据媒体类型（例如 text/plain 或 application/json）进行编码，然后必须进行百分号编码才能在 form-urlencoded 字符串中使用。

请注意，form-data 的基于内容的序列化不期望或要求数据中的百分号编码，只要求各部分请求头值中的百分号编码。

与历史规范的互操作性

在大多数情况下，严格遵守 [[RFC3986]] 生成查询字符串足以通过验证（包括 JSON Schema 的 format: "uri" 和 format: "uri-reference"），但某些 form-urlencoded 实现仍然期望使用稍微更严格的 [[RFC1738]] 规则。

由于所有符合 RFC1738 的 URI 都符合 RFC3986，因此需要确保历史互操作性的应用程序应使用 RFC1738 的规则。

与 Web 浏览器环境的互操作性

WHATWG 是一个面向 Web 浏览器的标准组织，它定义了一个“URL 实时标准”，用于在浏览器环境中解析和序列化 URL，包括解析和序列化 form-urlencoded 数据。WHATWG 的查询字符串百分号编码规则有所不同，取决于查询字符串是被视为form-urlencoded（在这种情况下，它需要比 [[RFC1738]] 更多的百分号编码）还是作为通用语法的一部分，后者允许 [[RFC3986]] 禁止的字符。

需要与 Web 浏览器实现最大兼容性的实现应使用 WHATWG 的 form-urlencoded 百分号编码规则。但是，它们不应依赖 WHATWG 宽松的通用查询字符串规则，因为由此产生的 URL 将无法通过 RFC3986 验证，包括 JSON Schema 的 format: uri 和 format: uri-reference。

解码 URI 和 `form-urlencoded` 字符串

百分号解码算法不关心哪些字符是否经过百分号解码，这意味着根据任何规范进行百分号编码的 URI 都将正确解码。

类似地，所有 form-urlencoded 解码算法只是在百分号解码算法中添加了 + 替换空格的处理，无论使用何种编码规范，它们都将正常工作。

然而，必须注意，如果 + 代表空格，则应使用 form-urlencoded 解码；如果 + 代表其字面值本身，则应使用常规的百分号解码。

百分号编码和非法或保留分隔符

[、]、| 和空格字符分别用作 deepObject、pipeDelimited 和 spaceDelimited 样式中的分隔符，它们都必须进行百分号编码以符合 [[RFC3986]]。这要求用户在使用这些样式之一时，以某种其他方式预编码参数名称和值中的字符，以将其与分隔符用法区分开来。

空格字符在所有相关标准的所有版本的所有实现中始终是非法的并以某种方式进行编码。虽然可以使用 form-urlencoded 约定中的 + 来区分参数名称和值中的空格与编码为 %20 的 spaceDelimited 分隔符，但规范将解码定义为单次通过，使得在解码结果中无法区分不同的用法。

某些环境在查询字符串中不编码地使用 [、] 和可能 | 而没有明显的困难，并且 WHATWG 的通用查询字符串规则不要求对它们进行百分号编码。依赖于不编码这些分隔符，同时在名称和值中使用常规百分号编码的代码，不能保证在所有实现之间都具有互操作性。

为了最大程度的互操作性，建议要么在对这些样式分隔符进行百分号编码的同时定义并记录额外的转义约定，要么完全避免使用这些样式。额外编码/转义的具体方法由 API 设计者决定，并且预计在本规范所述的序列化和编码之前执行，并在本规范的编码和序列化步骤反转之后再反转。这使其超出了本规范所管辖的流程。

附录 F：在引用文档中解析安全要求

本附录展示了如何检索一个 HTTP 可访问的多文档 OpenAPI 描述 (OAD)，并解析引用（非入口）文档中的 Security Requirement 对象。有关更多信息，请参阅解析隐式连接。

首先，入口文档是解析的起点。它将 MySecurity 安全方案定义为基于 JWT，并将 Path Item 定义为对另一个文档中组件的引用

GET /api/description/openapi HTTP/1.1
Host: www.example.com
Accept: application/openapi+json

"components": {
  "securitySchemes": {
    "MySecurity": {
      "type": "http",
      "scheme": "bearer",
      "bearerFormat": "JWT"
    }
  }
},
"paths": {
  "/foo": {
    "$ref": "other#/components/pathItems/Foo"
  }
}

GET /api/description/openapi HTTP/1.1
Host: www.example.com
Accept: application/openapi+yaml

components:
  securitySchemes:
    MySecurity:
      type: http
      scheme: bearer
      bearerFormat: JWT
paths:
  /foo:
    $ref: 'other#/components/pathItems/Foo'

此入口文档引用了另一个文档 other，而没有使用文件扩展名。这使得客户端能够根据资源逐个选择可接受的格式，前提是两种表示形式都可用

GET /api/description/other HTTP/1.1
Host: www.example.com
Accept: application/openapi+json

"components": {
  "securitySchemes": {
    "MySecurity": {
      "type": "http",
      "scheme": "basic"
    }
  },
  "pathItems": {
    "Foo": {
      "get": {
        "security": [
          "MySecurity": []
        ]
      }
    }
  }
}

GET /api/description/other HTTP/1.1
Host: www.example.com
Accept: application/openapi+yaml

components:
  securitySchemes:
    MySecurity:
      type: http
      scheme: basic
  pathItems:
    Foo:
      get:
        security:
          - MySecurity: []

在 other 文档中，被引用的路径项对安全方案 MySecurity 有一个安全要求。相同的安全方案存在于原始入口文档中。如解析隐式连接中所述，MySecurity 通过实现定义的行为进行解析。然而，该节中记载，建议工具从入口文档中解析组件名称。与所有实现定义的行为一样，检查工具文档以确定支持哪种行为非常重要。

OpenAPI 规范

版本 3.1.1

引言

定义

OpenAPI 描述

OpenAPI 文档

Schema

对象

路径模板

媒体类型

HTTP 状态码

大小写敏感性

未定义行为和实现定义行为

规范

版本

格式

OpenAPI 描述结构

解析文档

结构互操作性

解析隐式连接

数据类型

数据类型格式

处理二进制数据

从 OAS 3.0 迁移二进制描述

富文本格式

API 描述 URI 中的相对引用

API URL 中的相对引用

Schema

OpenAPI 对象

固定字段

信息对象

固定字段

信息对象示例

联系信息对象

固定字段

联系对象示例

许可证对象

固定字段

许可证对象示例

服务器对象

固定字段

服务器对象示例

服务器变量对象

固定字段

组件对象

固定字段

组件对象示例

路径对象

模式化字段

路径模板匹配

路径对象示例

路径项对象

固定字段

路径项对象示例

操作对象

固定字段

操作对象示例

外部文档对象

固定字段

外部文档对象示例

参数对象

参数位置

固定字段

常用固定字段

与 schema 一起使用的固定字段

与 content 一起使用的固定字段

样式值

样式示例

参数对象示例

请求体对象

固定字段

请求体示例

媒体类型对象

固定字段

媒体类型示例

文件上传的注意事项

支持 x-www-form-urlencoded 请求体

multipart 内容的特殊注意事项

编码对象

固定字段

与 `schema` 一起使用的固定字段

与 `content` 一起使用的固定字段

`multipart` 内容的特殊注意事项

编码 `x-www-form-urlencoded` 媒体类型

编码 `multipart` 媒体类型

`operationRef` 示例

与 `schema` 一起使用的固定字段

与 `content` 一起使用的固定字段

验证 `readOnly` 和 `writeOnly`