OpenAPI 3.0.0 是 OpenAPI 规范的第一个正式版本，因为它是由 SmartBear Software 捐赠给 OpenAPI Initiative，并在2015年从 Swagger 规范重命名为 OpenAPI 规范。
1.1 版本 3.0.0
文档里的关键词 "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" 都遵循 BCP 14 RFC2119 RFC8174 里的解释说明。
本文档 License： The Apache License, Version 2.0.
OpenAPI 规范（OAS），是定义一个标准的、与具体编程语言无关的RESTful API的规范。OpenAPI 规范使得人类和计算机都能在“不接触任何程序源代码和文档、不监控网络通信”的情况下理解一个服务的作用。如果您在定义您的 API 时做的很好，那么使用 API 的人就能非常轻松地理解您提供的 API 并与之交互了。
如果您遵循 OpenAPI 规范来定义您的 API，那么您就可以用文档生成工具来展示您的 API，用代码生成工具来自动生成各种编程语言的服务器端和客户端的代码，用自动测试工具进行测试等等。
3.1 OpenAPI 文档
一（或多）份用来定义或描述一个API的文档。
3.2 Path 模板
Path 模板指用大括号标记来标记一段 URL 作为可替换的路径参数。
3.3 Media Types
媒体类型定义分散于多处。 媒体类型定义应当符合RFC6838。
以下是一些媒体类型定义的示例：
3.4 HTTP状态码
HTTP状态码被用来表示一次请求的被执行状态。RFC7231定义了有效的状态码，可以在IANA Status Code Registry找到已经被注册的状态码的列表。
开放API规范使用符合语义化版本 2.0.0(semver)规范的版本号。
语义化版本的、部分（比如）应当被用来标记开放API规范的特性变动。通常 版本被用来表示本文档文档的错误修正而不是特性变动。支持开放API规范3.0的工具应该兼容所有3.0.*的版本，工具不应当关注修订版本号，比如和对它来说应该没有任何区别。
此后开放API规范的相同主版本号下更高次要版本的发布不应当对面向低于此次要版本号开发的工具的造成干扰。因此版本的规范应当可以在面向版本规范开发的工具内使用。
任何兼容开放API规范 3.*.* 的文档应当包含一个 字段用来表明它使用的规范的语义化版本。
一份遵从开放API规范的文档是一个自包含的JSON对象，可以使用JSON或YAML格式编写。
比如一个字段有一组值，用JSON格式表示为：
规范内的所有字段名都是小写。
字段分为两种：固定字段和模式字段。固定字段的字段名是确定的，模式字段的字段名需要符合一定的模式。
如果一个对象里有模式字段，那么在这个对象里的模式字段的名字不能有重复的。
为了保留在 YAML 和 JSON 格式之间转换的能力，推荐使用1.2版本的YAML格式，而且还需要符合以下限制：
- Tags 必须被限制在JSON Schema ruleset允许的范围内。
- Keys 必须是YAML Failsafe schema ruleset规范定义的纯字符串。
注意： 虽然API文档是使用 YAML 或 JSON 格式书写的，但是API的请求体和响应体或者其他内容可以是任何格式。
一份 OpenAPI 文档可以是单个文件也可以被拆分为多个文件， 连接的部分由用户自行决定。在后一种情形下，必须如 JSON Schema 中定义的那样使用 字段来相互引用。
推荐将根 OpenAPI 文档命名为 或 。
在 OAS 中的原始数据类型是基于 JSON Schema Specification Wright Draft 00 所支持的类型。注意 也作为一个被支持的类型并被定义为不包含小数或指数部分的 JSON 数字。 不是一个被支持的类型 (查看 来获得替代解决方案)。 Models 使用 Schema 对象 定义，这是一个 JSON Schema Specification Wright Draft 00 的扩展。
原始类型可以有一个可选的修饰属性：。 OAS 使用多个已知的格式来丰富类型定义。尽管如此，为了文档的需要， 属性被设计为一个 类型的开放属性值，可以包含任意值。比如 , 等未被此规范定义的格式也可以被使用。没有被定义的 属性类型遵从 JSON Schema 中的类型定义。无法识别某个 值的工具应该回退到 值，就像 未被指定一样。
被 OAS 定义的格式:
整个规范中的 字段被标记为支持 CommonMark markdown 格式。 OpenAPI 相关的工具在支持 CommonMark 0.27 中描述的富文本格式方面至少需要支持渲染 markerdown。相关工具为了安全考虑可以选择忽略某些 CommonMark 特性。
除非明确指定，所有 URL 类型的属性值都可以是相对地址，就如 RFC3986 中定义的那样以 作为 Base URI。
在 中的相对引用以 JSON Reference 为依据，以当前文档的 URL 作为 base URI. 同时参考 Reference 对象。
在接下来的叙述中，如果一个字段没有被明确的标记为 必选 或者被描述为 必须 或 应当，那么可以认为它是一个 可选 字段
这是OpenAPI document的根文档对象。
固定字段
这个对象提供API的元数据。如果客户端需要时可能会用到这些元数据，而且可能会被呈现在编辑工具或者文档生成工具中。
固定字段
Info 对象示例
所公开的API的联系人信息
固定字段
这个对象可能会被规范扩展扩展。
Contact 对象示例
公开API的证书信息。
固定字段
这个对象可能会被规范扩展扩展。
License 对象示例
表示一个服务器的对象。
固定字段
这个对象可能会被规范扩展扩展。
Server 对象示例
单个服务器可以这样描述：
以下内容表示的是有多个服务器时应该如何描述，比如OpenAPI 对象的：
以下内容展示了如何使用变量来配置服务器：
表示可用于服务器URL地址模板变量替换的对象。
固定字段
这个对象可能会被规范扩展扩展。
包含开放API规范固定的各种可重用组件。当没有被其他对象引用时，在这里定义定义的组件不会产生任何效果。
固定字段
这个对象可能会被 规范扩展 扩展。
上面定义的所有固定字段的值都是对象，对象包含的key的命名必须满足正则表达式： 。
字段名示例:
Components 对象示例
定义各个的端点和操作的相对路径。这里指定的路径会和 内指定的URL地址组成完整的URL地址，路径可以为空，这依赖于 ACL constraints 的设置。
模式字段
这个对象可能会被规范扩展扩展。
路径模板匹配
假设有以下路径，明确定义的路径 会被优先匹配：
以下路径被认为是等价的而且是无效的：
以下路径会产生歧义：
Paths 对象示例
描述对一个路径可执行的有效操作。依赖与 ACL constraints 的设置，一个Path Item可以是一个空对象，文档的读者仍然可以看到这个路径，但是他们将无法了解到对这个路径可用的任何操作和参数。
固定字段
这个对象可能会被规范扩展扩展。
Path Item 对象示例
描述对路径的某个操作。
固定字段
这个对象可能会被规范扩展扩展。
Operation 对象示例
允许引用外部资源来扩展文档。
固定字段
这个对象可能会被规范扩展扩展。
External Documentation 对象示例
Parameter 对象
描述一个操作参数。
一个参数的唯一性由 name 和 location 的组合来确定。
参数位置
有4种可能的参数位置值可用于字段：
- path - 与 Path Templating 一起使用，当参数的值是URL操作路径的一部分时可以使用，但是不包含主机地址或基础路径。比如在路径 中，路径参数是 。
- query - 追加在URL地址之后的参数，比如 中，查询参数是 。
- header - 请求中使用的自定义请求头，注意在 RFC7230 中规定，请求头的命名是不区分大小写的。
- cookie - 用于传递特定的cookie值。
固定字段
- 如果 的值是 ，那么 字段的值必须与其关联的 Paths 对象 内 path 字段的定义相呼应，查看 Path Templating 了解更多信息。
- 如果 的值是 而且字段的值是, 或 之一，那么此参数定义应该被忽略。
- 除此之外的情况，表示 属性的名字.
序列化参数的规则有两种。 对于简单的场景， 和 可以用于描述参数的结构和语法。
对于更复杂的场景，属性可以定义参数的媒体类型和概要。一个参数必须且只能包含和属性中的一个。当 或字段提供了对象时，示例必须遵照参数的序列化策略。
样式值
已经定义好了一组类型用于支持常见的通用的简单参数序列化。
Style 示例
建设一个参数名为包含如下之一的值：
下面这个表展示了各个不同类型值之间的例子。
这个对象可能会被规范扩展扩展。
Parameter 对象示例
一个值数组，数组元素为64位整数值的请求头参数：
一个值类型为字符串的路径参数：
一个值类型为字符串的可选查询参数，允许通过通过重复参数来传递多个值：
一个任意格式的查询参数，允许使用指定类型的未定义参数：
使用定义序列化方法的复杂参数：
定义请求体。
固定字段
这个对象可能会被规范扩展扩展。
Request Body 示例
一个引用了模型定义的请求体。
请求体是一个字符串的数组：
每种媒体类型对象都有相应的结构和示例来描述它。
固定字段
这个对象可能会被规范扩展扩展。
Media Type 示例
对文件上传的考虑
相对于2.0的规范，内容的上传与下载在开放API规范与其他类型一样使用相同的语法来描述。 特别的是:
这些示例同时适用于文件上传和下载。
一个使用操作提交文件的看起来像下面这样：
此外，可以指定明确的媒体类型：
为了同时上传多个文件，必须指定媒体类型：
x-www-form-urlencoded 请求体的支持
可以使用下面定义的格式来提交form url编码RFC1866的内容：
在这个示例中，在内容被传送到服务器之前，中的内容必须使用RFC1866中定义的方式字符串化。此外字段的复杂对象将会被字符串化。
当使用格式传送复杂对象时，默认的序列化策略在的 属性中定义为.
对内容的特别思考
使用作为来传送请求体是很常见的做法。相对于2.0版本的规范，当定义内容的输入参数时必须指定属性。这不但支持复杂的结构而且支持多文件上传机制。
当使用类型是，可以使用boundaries来分隔传送的内容，因此定义了以下默认的：
- 如果属性是一个原始值或者是一个原始值的数组，那么默认的Content-Type是
- 如果属性是复杂对象或者复杂对象的数组，那么默认的Content-Type是
- 如果属性是与或(也就是文件对象)的组合，那么默认的Content-Type是
示例:
这里介绍一下用来控制序列化请求体的属性，这个属性只适用于和类型的请求体。
Encoding 对象
一个编码定义仅适用于一个结构属性。
固定字段
这个对象可能会被规范扩展扩展。
Encoding 对象示例
Responses 对象
描述一个操作可能发生的响应的响应码与响应包含的响应体的对象。
一份API文档不必包含所有可能响应码，因为有些状态码无法提前预知。尽管如此，一份文档还是应当包含所有成功的响应和任何已知的错误响应。
字段可以用来标记一个响应适用于其他未被规范明确定义的HTTP响应码的默认响应。
一个必须至少包含一个响应码，而且是成功的响应。
固定字段
模式字段
这个对象可能会被规范扩展扩展。
Responses 对象示例
一个代表成功操作的 200 响应和一个代表其他操作状态的默认响应（暗示是一个错误）：
描述单个API操作的响应，包括设计时间、基于不同响应也包括到相应操作的静态
固定字段
这个对象可能会被规范扩展扩展。
Response 对象示例s
一个包含复杂类型的数组格式的响应：
字符串类型的响应：
带HTTP头的普通文本类型的响应：
没有返回值的响应：
A map of possible out-of band callbacks related to the parent operation. 映射中的每个值都是一个描述一组可能会被API提供者发起的请求和相应的响应的 Path Item 对象 。用以标识回调对象的键是一个表达式，表达式会在运行时被计算，得到的值作为回调操作的URL。
模式字段
这个对象可能会被规范扩展扩展。
Key Expression
用于标识 Path Item 对象 的键是一个 runtime expression，此表达式会在运行时的HTTP请求/响应上下文中被计算，计算结果用于表示回调请求的URL。 一个简单的例子是 。 However, using a runtime expression the complete HTTP message can be accessed. This includes accessing any part of a body that a JSON Pointer RFC6901 can reference.
比如有如下 HTTP 请求：
下方示例展示了各种表达式是如何被计算，这里假设回调操作有一个名为 的路径参数和一个名为 的查询参数。
Callback 对象示例
如下示例展示了一个通过请求体内的 和 属性指定的URL的回调。
固定字段
这个对象可能会被规范扩展扩展。
In all cases, the example value is expected to be compatible with the type schema of its associated value. Tooling implementations MAY choose to validate compatibility automatically, and reject the example value(s) if incompatible.
Example 对象示例
The represents a possible design-time link for a response. The presence of a link does not guarantee the caller's ability to successfully invoke it, rather it provides a known relationship and traversal mechanism between responses and other operations.
Unlike dynamic links (i.e. links provided in the response payload), the OAS linking mechanism does not require link information in the runtime response.
For computing links, and providing instructions to execute them, a runtime expression is used for accessing values in an operation and using them as parameters while invoking the linked operation.
固定字段
这个对象可能会被规范扩展扩展。
A linked operation MUST be identified using either an or . In the case of an , it MUST be unique and resolved in the scope of the OAS document. Because of the potential for name clashes, the syntax is preferred for specifications with external references.
Examples
Computing a link from a request operation where the is used to pass a request parameter to the linked operation.
When a runtime expression fails to evaluate, no parameter value is passed to the target operation.
Values from the response body can be used to drive a linked operation.
Clients follow all links at their discretion. Neither permissions, nor the capability to make a successful call to that link, is guaranteed solely by the existence of a relationship.
OperationRef Examples
As references to MAY NOT be possible (the is an optional value), references MAY also be made through a relative :
or an absolute :
Note that in the use of , the escaped forward-slash is necessary when using JSON references.
Runtime Expressions
Runtime expressions allow defining values based on information that will only be available within the HTTP message in an actual API call. This mechanism is used by Link 对象 and Callback 对象.
The runtime expression is defined by the following ABNF syntax
The identifier is case-sensitive, whereas is not.
The table below provides examples of runtime expressions and examples of their use in a value:
Examples
Runtime expressions preserve the type of the referenced value. Expressions can be embedded into string values by surrounding the expression with curly braces.
Header 对象除了以下改动之外与 Parameter 对象 一致：
- 不能被指定，它在相应的 映射中被指定。
- 不能被指定，它隐含在 中。
- 所有被 location 影响的特性必须适合 中的一个 location，(比如 )。
Header 对象示例
一个类型为 的简单 header：
Adds metadata to a single tag that is used by the Operation 对象. It is not mandatory to have a Tag Object per tag defined in the Operation Object instances.
固定字段
这个对象可能会被规范扩展扩展。
Tag 对象示例
Examples 对象
In an , a JSON Reference MAY be used, with the explicit restriction that examples having a JSON format with object named are not allowed. Therefore, that , structurally, can be either a string primitive or an object, similar to .
In all cases, the payload is expected to be compatible with the type schema for the associated value. Tooling implementations MAY choose to validate compatibility automatically, and reject the example value(s) if they are incompatible.
一个允许引用规范内部的其他部分或外部规范的对象。
Reference 对象 定义于 JSON Reference 且遵循相同的结构、行为和规则。
For this specification, reference resolution is accomplished as defined by the JSON Reference specification and not by the JSON Schema specification.
固定字段
此对象不能被扩展，任何附加的属性将会被忽略。
Reference 对象示例
关联外部文档示例
关联外部文档的一部分
Schema 对象 用于定义输入和输出的数据类型。这些类型可以是对象，但也可以是原始值和数组。这个对象是 JSON Schema Specification Wright Draft 00 扩展后的子集.
关于property的的更多信息请查看 JSON Schema Core 和 JSON Schema Validation。除非另有说明，否则 properties 定义遵循JSON Schema。
Properties
以下 properties 是直接从 JSON Schema 提取出来的，而且遵循同样的规范：
- title
- multipleOf
- maximum
- exclusiveMaximum
- minimum
- exclusiveMinimum
- maxLength
- minLength
- pattern (This string SHOULD be a valid regular expression, according to the ECMA 262 regular expression dialect)
- maxItems
- minItems
- uniqueItems
- maxProperties
- minProperties
- required
- enum
以下 properties 是从 JSON Schema 提取出来的，但是做了一些调整以适应 OpenAPI Specification。
- type - 值必须是一个字符串，不支持以数组形式定义多个值。
- allOf - Inline 或 referenced 的 schema 必须是一个 Schema 对象 且不是一个标准的 JSON Schema。
- oneOf - Inline 或 referenced 的 schema 必须是一个 Schema 对象 且不是一个标准的 JSON Schema。
- anyOf - Inline 或 referenced 的 schema 必须是一个 Schema 对象 且不是一个标准的 JSON Schema。
- not - Inline 或 referenced 的 schema 必须是一个 Schema 对象 且不是一个标准的 JSON Schema。
- items - 值必须是一个对象且不是一个数组。Inline 或 referenced 的 schema 必须是一个 Schema 对象且不是一个标准的 JSON Schem。. 必须存在如果 的值是 。
- properties - Property 定义必须是一个 Schema 对象 且不是一个标准的 JSON Schema (inline 或 referenced).
- additionalProperties - 值可以是 boolean 或 object. Inline 或 referenced schema 必须是一个 Schema 对象 且不是一个标准的 JSON Schema。
- description - CommonMark syntax可以被用来呈现富文本格式.
- format - 查看 Data Type Formats 以深入了解细节。在依靠 JSON Schema 定义的格式的同时，OAS 额外提供了一些预定义的格式。
- default - The default value represents what would be assumed by the consumer of the input as the value of the schema if one is not provided. 不同于 JSON Schema，这个值必须符合定义与相同级别的 Schema 对象 中定义的类型，比如 是 ，那么 可以是 但不能是 。
另外，任何可以使用 Schema 对象 的地方也可以使用 Reference 对象 替代。这允许引用一个定义而避免重复定义。
未在此处提及的 JSON Schema 规范中定义的其他属性将严格的不被支持。
Other than the JSON Schema subset fields, 以下字段可能会被用于后续的 schema documentation：
固定字段
这个对象可能会被规范扩展扩展。
Composition and Inheritance (Polymorphism)
The OpenAPI Specification allows combining and extending model definitions using the property of JSON Schema, in effect offering model composition. takes an array of object definitions that are validated independently but together compose a single object.
While composition offers model extensibility, it does not imply a hierarchy between the models. To support polymorphism, the OpenAPI Specification adds the field. When used, the will be the name of the property that decides which schema definition validates the structure of the model. As such, the field MUST be a required field. There are are two ways to define the value of a discriminator for an inheriting instance.
- Use the schema name.
- Override the schema name by overriding the property with a new value. If a new value exists, this takes precedence over the schema name.
As such, inline schema definitions, which do not have a given id, cannot be used in polymorphism.
XML Modeling
The xml property allows extra definitions when translating the JSON definition to XML. The XML 对象 contains additional information about the available options.
Schema 对象示例s
Primitive Sample
Simple Model
Model with Map/Dictionary Properties
For a simple string to string mapping:
For a string to model mapping:
Model with Example
Models with Composition
Models with Polymorphism Support
当一个 request bodies 或 response payloads 可以是多种 schemas 时，可以使用一个 对象来帮助序列化、反序列化和校验。 The discriminator is a specific object in a schema which is used to inform the consumer of the specification of an alternative schema based on the value associated with it.
当使用 discriminator 时，inline schemas 不会被考虑。
固定字段
discriminator 属性仅在与 , , 这几个复合关键字之一一起使用时才合法.
在 OAS 3.0 中，一个 response payload 仅可以使用一种类型来描述：
也就是说 payload 必须 且只能满足 、 或 schemas 中的一个。 In this case, a discriminator MAY act as a "hint" to shortcut validation and selection of the matching schema which may be a costly operation, depending on the complexity of the schema. We can then describe exactly which field tells us which schema to use:
The expectation now is that a property with name MUST be present in the response payload, and the value will correspond to the name of a schema defined in the OAS document. Thus the response payload:
Will indicate that the schema be used in conjunction with this payload.
In scenarios where the value of the discriminator field does not match the schema name or implicit mapping is not possible, an optional definition MAY be used:
Here the discriminator value of will map to the schema , rather than the default (implicit) value of . If the discriminator value does not match an implicit or explicit mapping, no schema can be determined and validation SHOULD fail. Mapping keys MUST be string values, but tooling MAY convert response values to strings for comparison.
When used in conjunction with the construct, the use of the discriminator can avoid ambiguity where multiple schemas may satisfy a single payload.
In both the and use cases, all possible schemas MUST be listed explicitly. To avoid redundancy, the discriminator MAY be added to a parent schema definition, and all schemas comprising the parent schema in an construct may be used as an alternate schema.
For example:
a payload like this:
will indicate that the schema be used. Likewise this schema:
will map to because of the definition in the element.
一个为 XML 模型定义微调过的元数据对象。
当使用数组时，不会推测 XML 元素的名称（单数或复数形式），所以应该添加 属性来提供此信息。 查看展示此期望的示例。
固定字段
这个对象可能会被规范扩展扩展。
XML 对象示例
XML 对象定义的示例被包括在一个 Schema 对象 的特性定义并带有一个样例 XML 来呈现它。
无 XML 元素
基础字符串属性：
基础字符串数组属性 ( 默认是 )：
XML 名称替换
XML 属性，前缀和命名空间
在此示例中展示了一个完整的模型定义。
XML 数组
改变元素的名称：
外部的 属性在 XML 上不产生效果：
尽管数组是被包裹的，如果没有明确定义一个名称，那么同样地名称会被用于内部和外部：
为了解决上面示例的命名问题，可以使用下面的定义：
Affecting both internal and external names:
如果我们改变外部的元素而保持内部的不变：
定义一个用于 operations 的 security scheme。被支持的 schemes 有 HTTP 认证，一个 API key（作为 header 或 query parameter），定义于RFC6749 的 Oauth2 常用流程（implicit、password、application 和 access code）和 OpenID Connect Discovery。
固定字段
这个对象可能会被规范扩展扩展。
Security Scheme 对象示例
Basic Authentication Sample
API Key Sample
JWT Bearer Sample
Implicit OAuth2 Sample
允许配置支持的 OAuth Flows。
固定字段
这个对象可能会被规范扩展扩展。
OAuth Flow 对象
支持的 OAuth Flow 的配置详情。
固定字段
这个对象可能会被规范扩展扩展。
OAuth Flow 对象示例s
列出执行此 operation 所需的 security schemes。每个属性的名字都必须与Components 对象 中 Security Schemes 声明的 security scheme 相符。
包含多个 schemes 的 Security Requirement 对象中的所有 scheme 都必须要满足授权请求。这便能够支持需要使用多个 query parameters 或 HTTP headers 来传递安全信息的情景。
当When a list of Security Requirement Objects is defined on the Open API 对象 或 [Operation 对象] (#operationObject) 包含一组 Security Requirement 对象时，请求只需要满足其中一个即可。
模式字段
Security Requirement 对象示例
Non-OAuth2 Security Requirement
OAuth2 Security Requirement
尽管 OpenAPI Specification 尝试包含大部分的使用场景，在需要时仍然可以通过附加数据来扩展此规范。
此扩展属性被设计为总是以 为前缀的模式字段。
此扩展可能会也可能不会被当前的工具支持，但是可以请求工具开发者支持此扩展（如果工具是内部或开源的）。
Some objects in the OpenAPI Specification MAY be declared and remain empty, or be completely removed, even though they are inherently the core of the API documentation.
The reasoning is to allow an additional layer of access control over the documentation. While not part of the specification itself, certain libraries MAY choose to allow access to parts of the documentation based on some form of authentication/authorization.
Two examples of this:
- The Paths 对象 MAY be empty. It may be counterintuitive, but this may tell the viewer that they got to the right place, but can't access any documentation. They'd still have access to the Info 对象 which may contain additional information regarding authentication.
- The Path Item 对象 MAY be empty. In this case, the viewer will be aware that the path exists, but will not be able to see any of its operations or parameters. This is different than hiding the path itself from the Paths 对象, so the user will not be aware of its existence. This allows the documentation provider to finely control what the viewer can see.
版权声明：
本文来源网络，所有图片文章版权属于原作者，如有侵权，联系删除。
本文网址：https://www.mushiming.com/mjsbk/5593.html