OpenAPI 规范的最新版本，OpenAPI 3.0 (OAS 3.0)，已于去年发布，并正被寻求标准化 OAS 的 API 开发者和组织广泛采用。
OAS 3.0 是该规范自 2015 年捐赠给 OpenAPI 倡议，并从 Swagger 规范更名为 OpenAPI 规范以来的第一个主要版本。
去年年底，我们有幸邀请到 OpenAPI 倡议的两位成员，OAI 技术指导委员会成员（同时也是 SmartBear 的 Swagger 开发者布道师）Ron Ratovsky，以及 OAI 董事会主席 Ole Lensmar，共同探讨 OAS 3.0 的最新功能和增强。
在这 60 分钟的演示中，演讲者分享了他们对规范重构方式、他们最兴奋的新功能以及 API 团队如何开始过渡到 OAS 3.0 的见解。
我们讨论的完整视频可在此处观看。但我们也希望提供更详细的分解，包含演示中的片段和主要要点。
本文中，我们将分享 OAS 最新版本的一些主要更新，并详细介绍您在过渡到 OAS 3.0 时需要了解的内容。
简化结构，提高可复用性
OAS 3.0 引入了一种新的、更简化的结构。新结构旨在使 OAS 定义的编写和导航更容易——它结合了 OAS 2.0 中的一些现有对象，标准化了规范不同部分的命名，甚至引入了新对象以扩展 OAS 3.0 内部的可复用性。
可复用组件的数量从 4 个增加到 9 个，新增了 链接（Links）和 回调（Callbacks）等功能，我们将在本文后面更详细地介绍这些功能。
了解更多
阅读文档： OpenAPI 3.0 结构
内容协商支持
OAS 3.0 对请求体和响应体的定义方式引入了多项更改。一个重要变化是，body 和 formdata 参数已被移除，并由 requestBody 替代。requestBody 更具灵活性，因为它允许您使用不同的媒体类型，例如 JSON、XML、表单数据、纯文本等，并为不同的媒体类型使用不同的模式（schema）。
其他重要更改包括
- 操作现在可以同时使用表单数据（formdata）和其他媒体类型，例如 JSON。
- consumes 数组被 requestBody.content 映射取代，该映射将媒体类型映射到其模式（schema）。
- 模式（schema）可以因媒体类型而异。
- 表单数据现在可以包含对象，并且您可以指定对象和数组的序列化策略。
了解更多
阅读文档： 描述请求体
增强的安全定义
虽然 OAS 3.0 中安全定义的结构与 OAS 2.0 保持一致，但仍有一些关键变化会影响您描述安全流的方式。其中最值得注意的是，OAuth 2 流已重命名以匹配 OAuth 2 规范：accessCode 现已更名为 authorizationCode，application 现已更名为 clientCredentials。
其他更改包括
- securityDefinitions 已重命名为 securitySchemes 并移至 components 内部。
- type: basic 已被 type: http 和 scheme: basic 取代。
- 新的 type: http 是所有 HTTP 安全方案的伞形类型，包括 Basic、Bearer 等，scheme 关键字表示方案类型。
- API 密钥现在可以通过 in: cookie 发送。
- 增加了对 OpenID Connect Discovery（type: openIdConnect）的支持。
- OAuth 2 安全方案现在可以定义多个流（flows）。
了解更多
阅读文档： 身份验证和授权
更新的参数类型
如前所述，OAS 3.0 移除了两种参数类型：body 和 formdata。OAS 3.0 还引入了一种新的参数类型 cookie，这是对当前使用 cookie 的 API 进行文档化的一项请求更新。
OpenAPI 3.0 还支持在操作参数中使用数组和对象，并允许您指定这些参数应如何序列化。序列化方法由 style 和 explode 关键字定义。
OpenAPI 序列化规则基于 RFC 6570 定义的 URI 模板模式子集。
了解更多
阅读文档： 描述参数
改进的示例
示例是 API 文档化的重要组成部分。OAS 3.0 全面改进了示例在规范中的使用方式，包括描述多个示例、在 API 定义中重用示例以及引用外部示例的能力。
对示例的更改在使用示例对象时提供了更高的可复用性。
了解更多
阅读文档： 添加示例
引入 OpenAPI 链接
链接是 OpenAPI 3.0 的新功能之一。链接在 API 设计阶段引入了一个全新的概念，用于在设计 API 时显示响应和操作之间的关系。
使用链接，您可以描述一个操作返回的各种值如何用作其他操作的输入。通过这种方式，链接提供了操作之间已知的关系和遍历机制。链接的概念通常与超媒体（hypermedia）相比较，但 OpenAPI 链接不要求实际响应中存在链接信息。
阅读文档： OpenAPI 链接
支持描述回调
OAS 3.0 支持描述回调（callbacks），可用于定义异步 API 或 Webhook。回调允许您处理您的服务响应某些事件时将发送到其他服务的请求。这有助于您改善 API 为客户端提供的工作流程。
回调使用与其他路径定义相同的结构，并允许您描述客户端为了使 Webhook 工作需要实现什么。
阅读文档： 回调
OAS 3.0 中的其他更改
除了 OpenAPI 3.0 的一些主要更改之外，在过渡到 OAS 3.0 时，还有一些额外的更新需要了解。
- OAS 3.0 从 GitHub Flavored Markdown (GFM) 转向支持 CommonMark。
- 扩展的 JSON Schema 支持，包括
anyOf、oneOf 和 not。
- 定义多个服务器和模板服务器定义
- 新增对 TRACE 方法的支持
从 OAS 2.0 到 OAS 3.0 的破坏性变更
如果您准备开始转换为 OAS 3.0，可以使用工具来帮助重构现有定义。SwaggerHub 提供内置转换器，可将您现有规范转换为 3.0 兼容格式，让您轻松上手。
在开始转换过程时，您还需要关注几个重要方面
- Definitions、parameters、responses 和 securityDefinitions 都已移至 components 下
- Schemes、hosts 和 basePaths 已被 servers 替换
- 参数需要重构
- 类型定义移至 schema 下
- Body 和 formdata 参数提取到 requestBody 中
- 响应需要重构
- 部分安全定义变更
- 'basic' 更改为 'http'
- OAuth2 流已重命名，并具有略微不同的结构
OAS 3.0 的其他资源
您可以在开源 Swagger Editor 和 Swagger UI 中，或在 SwaggerHub 平台内使用 OAS 3.0 开始设计和文档化 API。我们还整理了一些我们最喜欢的 OAS 3.0 资源，以帮助您入门。