规范

版本

开放 API 规范使用符合语义化版本 2.0.0(semver)规范的版本号。

语义化版本的主版本号、次版本号部分（比如3.0）应当被用来标记开放 API 规范的特性变动。通常 .修订号 版本被用来表示本文档文档的错误修正而不是特性变动。支持开放 API 规范 3.0 的工具应该兼容所有 3.0.*的版本，工具不应当关注修订版本号，比如3.0.0和3.0.1对它来说应该没有任何区别。

此后开放 API 规范的相同主版本号下更高次要版本的发布不应当对面向低于此次要版本号开发的工具的造成干扰。因此3.1.0 版本的规范应当可以在面向3.0.0版本规范开发的工具内使用。

任何兼容开放 API 规范 3.*.* 的文档应当包含一个openapi 字段用来表明它使用的规范的语义化版本。

格式

一份遵从开放 API 规范的文档是一个自包含的 JSON 对象，可以使用 JSON 或 YAML 格式编写。

比如一个字段有一组值，用 JSON 格式表示为：

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

规范内的所有字段名都是小写。

字段分为两种：固定字段和模式字段。固定字段的字段名是确定的，模式字段的字段名需要符合一定的模式。

如果一个对象里有模式字段，那么在这个对象里的模式字段的名字不能有重复的。

为了保留在 YAML 和 JSON 格式之间转换的能力，推荐使用1.2版本的 YAML 格式，而且还需要符合以下限制：

• Tags 必须被限制在JSON Schema ruleset允许的范围内。
• Keys 必须是YAML Failsafe schema ruleset规范定义的纯字符串。

注意： 虽然 API 文档是使用 YAML 或 JSON 格式书写的，但是 API 的请求体和响应体或者其他内容可以是任何格式。

文档结构

一份 OpenAPI 文档可以是单个文件也可以被拆分为多个文件， 连接的部分由用户自行决定。在后一种情形下，必须如 JSON Schema 中定义的那样使用 $ref 字段来相互引用。

推荐将根 OpenAPI 文档命名为openapi.json 或 openapi.yaml。

数据类型

在 OAS 中的原始数据类型是基于 JSON Schema Specification Wright Draft 00 所支持的类型。注意 integer 也作为一个被支持的类型并被定义为不包含小数或指数部分的 JSON 数字。 null 不是一个被支持的类型 (查看 nullable 来获得替代解决方案)。 Models 使用 Schema 对象 定义，这是一个 JSON Schema Specification Wright Draft 00 的扩展。

原始类型可以有一个可选的修饰属性：`format`。 OAS 使用多个已知的格式来丰富类型定义。尽管如此，为了文档的需要，`format` 属性被设计为一个 `string` 类型的开放属性值，可以包含任意值。比如 `"email"`, `"uuid"` 等未被此规范定义的格式也可以被使用。没有被定义的 `format` 属性类型遵从 JSON Schema 中的类型定义。无法识别某个 `format` 值的工具应该回退到 `type` 值，就像 `format` 未被指定一样。

被 OAS 定义的格式:

通用名	type	format	备注
integer	integer	int32	32 位有符号
long	integer	int64	64 位有符号
float	number	float
double	number	double
string	string
byte	string	byte	base64 编码的支付
binary	string	binary	任意 8 进制序列
boolean	boolean
date	string	date	定义于 full-date - RFC3339
dateTime	string	date-time	定义于 date-time - RFC3339
password	string	password	告知输入界面不应该明文显示输入信息。

富文本格式

整个规范中的 description 字段被标记为支持 CommonMark markdown 格式。 OpenAPI 相关的工具在支持 CommonMark 0.27 中描述的富文本格式方面至少需要支持渲染 markerdown。相关工具为了安全考虑可以选择忽略某些 CommonMark 特性。

URL 的关联引用

除非明确指定，所有 URL 类型的属性值都可以是相对地址，就如 RFC3986 中定义的那样以 Server 对象 作为 Base URI。

在 $ref 中的相对引用以 JSON Reference 为依据，以当前文档的 URL 作为 base URI.  同时参考 Reference 对象。