OpenAPI 描述结构

OpenAPI 描述 (OAD) 在一个或多个机器可读文档（文件或网络资源）中描述了一个类似 HTTP 的 API。本页描述了这些文档的语法以及它们必须包含的最小结构。

OpenAPI 描述语法

OpenAPI 描述被写成一个或多个文本文档。每个文档代表一个 JSON 对象，以 JSON 或 YAML 格式。引用用于将 JSON 对象的各个部分相互链接，而这种链接结构构成了完整的 OpenAPI 描述。解析从一个 OpenAPI 对象开始，包含该对象的文档被称为入口文档，通常称为 openapi.json 或 openapi.yaml。

本节非常简要地描述和比较了 JSON 和 YAML 数据格式。

JSON 可以表示数字、字符串、布尔值、null 值、数组和对象。数组是有序的值列表，这些值可以具有不同的类型。对象（也称为映射）是名称-值对的集合，其中名称（也称为键或字段）在对象中是唯一的，而值可以具有任何支持的类型（包括其他对象或数组）。

以下是一个比较，显示了不同的语法。

JSON

{
  "anObject": {
    "aNumber": 42,
    "aString": "This is a string",
    "aBoolean": true,
    "nothing": null,
    "arrayOfNumbers": [
      1,
      2,
      3
    ]
  }
}

YAML

# Anything after a hash sign is a comment
anObject:
  aNumber: 42
  aString: This is a string
  aBoolean: true
  nothing: null
  arrayOfNumbers:
    - 1
    - 2
    - 3

基本上，JSON 不支持注释，并且要求：逗号分隔字段，花括号括起对象，双引号括起字符串，方括号括起数组。另一方面，YAML 在数组项之前需要连字符，并且严重依赖缩进，这在大型文件上可能很麻烦（缩进在 JSON 中完全是可选的）。

YAML 通常更受欢迎，因为它的大小略小，但两种格式完全可以互换（只要使用 YAML 1.2）。这些页面中的所有示例都将以 YAML 格式给出。

但是，YAML 是 JSON 的超集，这意味着两种语法可以混合使用。虽然这在一般情况下不建议，但有时会很方便。例如

anObject:
  aString: This is a string
  arrayOfNumbers: [ 1, 2, 3 ] # Abbreviated array representation

最后，对象字段名称区分大小写：openapi 与 OpenAPI 不同。

注意： 本指南中使用省略号 (…) 来表示不完整的代码片段。省略号不是 JSON 或 YAML 的一部分。

最小 OpenAPI 描述结构

为了完全准确，最小的 OpenAPI 描述 (OAD) 是一个包含符合 OpenAPI 规范 (OAS) 中定义的结构的字段的单个 JSON 对象。

OAS 结构很长也很复杂，因此本节只描述了它必须包含的最小字段集，而接下来的页面将详细介绍特定对象。 OpenAPI 地图是一款不错的可视化工具，可以帮助读者熟悉这个长的规范。

任何 OpenAPI 描述中的根对象都是 OpenAPI 对象，它只有两个字段是强制性的：openapi 和 info。此外，至少需要 paths、components 或 webhooks 中的一个。

openapi (string): 这表示此 OAD 使用的 OAS 版本，例如“3.1.0”。使用此字段，工具可以检查描述是否正确遵循规范。
info (信息对象): 这提供了有关 API 的一般信息（如其描述、作者和联系信息），但唯一强制的字段是 title 和 version。
- title (string): API 的人类可读名称，如“GitHub REST API”，有助于保持 API 集合井然有序。
- version (string): 表示API 描述的版本（不要与上面的 OAS 版本混淆）。工具可以使用此字段生成代码，以确保客户端和服务器通过 API 的相同版本进行交互，例如。
paths (路径对象): 这描述了 API 的所有端点，包括其参数和所有可能的服务器响应。服务器和客户端代码可以从这个描述中生成，连同其文档一起。

本指南中使用图表来显示不同对象之间的关系。

以下是一个最小 OpenAPI 描述的示例

openapi: 3.1.0
info:
  title: A minimal OpenAPI Description
  version: 0.0.1
paths: {} # No endpoints defined

此 API 没什么用，因为它没有定义任何操作（它没有端点）。下一页将解决这个问题。

总结

本页展示了

用于编写 OpenAPI 描述的语法（语言）可以是JSON、YAML 或两者。
OpenAPI 描述是一个 JSON 对象，其中包含 OpenAPI 规范中描述的字段。
每个 OpenAPI 描述都必须包含一个 OpenAPI 对象，其中至少包含 openapi 和 info 字段，以及 paths、components 或 webhooks 中的一个。

下一页描述了 paths 字段的内容，以便可以将端点添加到上面的最小片段中。