OpenAPI 规范（OAS），是定义一个标准的、与具体编程语言无关的 RESTful API 的规范。OpenAPI 规范使得人类和计算机都能在“不接触任何程序源代码和文档、不监控网络通信”的情况下理解一个服务的作用。如果您在定义您的 API 时做的很好，那么使用 API 的人就能非常轻松地理解您提供的 API 并与之交互了。
如果您遵循 OpenAPI 规范来定义您的 API，那么您就可以用文档生成工具来展示您的 API，用代码生成工具来自动生成各种编程语言的服务器端和客户端的代码，用自动测试工具进行测试等等。
一（或多）份用来定义或描述一个 API 的文档。
Path 模板指用大括号标记来标记一段 URL 作为可替换的路径参数。
媒体类型定义分散于多处。 媒体类型定义应当符合RFC6838。
以下是一些媒体类型定义的示例：
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 的扩展。
原始类型可以有一个可选的修饰属性：`format`。 OAS 使用多个已知的格式来丰富类型定义。尽管如此，为了文档的需要，`format` 属性被设计为一个 `string` 类型的开放属性值，可以包含任意值。比如 `"email"`, `"uuid"` 等未被此规范定义的格式也可以被使用。没有被定义的 `format` 属性类型遵从 JSON Schema 中的类型定义。无法识别某个 `format` 值的工具应该回退到 `type` 值，就像 `format` 未被指定一样。
被 OAS 定义的格式:
整个规范中的 字段被标记为支持 CommonMark markdown 格式。 OpenAPI 相关的工具在支持 CommonMark 0.27 中描述的富文本格式方面至少需要支持渲染 markerdown。相关工具为了安全考虑可以选择忽略某些 CommonMark 特性。
除非明确指定，所有 URL 类型的属性值都可以是相对地址，就如 RFC3986 中定义的那样以 作为 Base URI。
在 中的相对引用以 JSON Reference 为依据，以当前文档的 URL 作为 base URI. 同时参考 Reference 对象。
版权声明：
本文来源网络，所有图片文章版权属于原作者，如有侵权，联系删除。
本文网址：https://www.mushiming.com/mjsbk/12448.html