随着 OpenAPI 规范 3.0 版本即将发布候选版本，本系列文章旨在深入了解正在发生的变化以及变化的方式。第一篇文章介绍了规范下一步演进的背景和基本原理，接下来的几篇文章将介绍技术开发者社区 (TDC) 到目前为止取得的进展。
为了组织工作，创建了六个总括性元问题
- 结构改进
- 请求参数
- 协议和有效负载
- 文档
- 安全性
- 路径定义
在接下来的几周内，我们将按顺序描述每个问题。今天，我们将介绍……
结构改进
下一个版本的 OpenAPI 将会进行一些重大更改——在语义版本控制术语中，这将代表从 2.0 到 3.0 的重大更改。由于重大更改事件很少发生，因此它们提供了进行全面结构改进的机会。
最重要的是，在 OpenAPI 规范 3.0 版本中，文档的整体结构得到了简化
新版本标识符
从曾经被称为 Swagger 2.0，现在称为 OpenAPI 规范的描述开始过渡，最明显的地方是什么？名为 swagger 的 2.0 版本属性将被 openapi 版本标识符替换。今后，此版本标识符将遵循语义版本控制的约定，因此它将具有三个部分：主版本.次版本.修订版本，这意味着 3.0.0。这也解释了为什么值是字符串而不是数字，它将允许将来对规范进行更加可控和可识别的更改。
组件对象
OpenAPI 2.0 在根级属性的行为方面有些前后不一致。例如，一些属性包含应用于 API 的全局元数据，而其他属性则用作可重用元数据片段的容器，以便在其他地方引用。为了澄清这一点并最大程度地减少根级属性的数量，将引入一个新的 components 属性。此components 属性仅包含将在文档其他地方引用的可重用元数据。
多个主机
OpenAPI 2.0 允许指定单个主机和 basePath，但 schemes 属性允许指定 http 和 https，因此实际上启用了两个主机，它们仅在方案方面有所不同。在 OpenAPI.vNext 中，规范存储库的工作分支，新的根级 hosts 对象包含一个对象数组，该数组包含 host、basePath 和 scheme 属性。通过将其结构化为对象数组，可以支持 API 的任意数量的根 URL，并允许更清晰地关联 scheme、host 和 basePath 属性。它还减少了所需的根级属性数量，简化了文档结构。
在围绕 GitHub 问题和相关拉取请求的讨论中，TDC 解决了路径是否可以被识别为代表不同环境（如开发、测试和生产）的问题。但是，这将暗示不同的主机可能指向不同的 API 实现，而这并非支持 API 的多个根 URL 的目的。相反，目标是允许为同一 API 定义一组别名。（注意：关于主机和 basePath 的参数化仍然存在一个未解决的问题，这可能允许指向不同的环境。）
此外，可以在路径项级别覆盖 host、basePath 和 scheme。这将使将独立主机上提供的功能合并到 API 描述中变得更加容易。
更具描述性的选项
新规范允许用户以更面向资源的方式描述他们的 API。以前，API 行为的描述是在操作级别定义的。对于以面向资源的方式设计的 API，文档文本通常写为“获取 foo”、“发布 foo”、“删除 foo”。如果需要详细说明“foo”的目的，则必须为每个操作重复该文本。现在，路径项对象可以包含简短的摘要文本和更长的描述文本。是否在操作级别提供其他描述的选择留给用户决定，具体取决于是否需要进一步解释。
示例对象
描述示例的选项已大幅扩展。以前的规范表明示例只能通过 JSON 或 YAML 对象来描述。现在，通过使用 JSON 字符串，可以描述任何格式的示例。此外，$ref 对象可用于指向包含示例的外部文件。结构化示例的确切方法仍在不断变化，可能取决于 TDC 是否接受建议的内容对象。内容对象包含一个示例对象数组，用于为每个媒体类型定义一个或多个示例。
如您所见，关于结构更改的这个元问题有很多内容需要消化。下一篇文章将讨论 OpenAPI 3.0 中如何描述请求的更改。
- 本系列文章的上一篇文章 第 1 部分 - 背景 以及如何参与！
—
关于作者
Darrel Miller
Darrel Miller 是微软 Azure API Management 的高级软件开发工程师。Darrel 是 OpenAPI 规范技术开发者社区的成员。你可以在推特 或他的博客Bizcoder上关注他。