最新版本的 OpenAPI 规范，OpenAPI 3.0 (OAS 3.0)，已于去年发布，并且已经获得了 API 开发人员和希望在 OAS 上标准化的组织的采用。
OAS 3.0 是该规范捐赠给 OpenAPI Initiative 并在 2015 年从 Swagger 规范重命名为 OpenAPI 规范以来的第一个主要版本。
在去年年底，我们有机会与 OpenAPI Initiative 的两位成员，OAI 技术指导委员会成员 Ron Ratovsky（也是 SmartBear 的 Swagger 开发布道师）以及 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 个，增加了诸如 链接 和 回调 等新功能，我们将在本文后面详细介绍。
了解更多
阅读文档： OpenAPI 3.0 结构
内容协商支持
OAS 3.0 对如何定义请求和响应的主体进行了许多更改。一个重要的变化是，主体和 formdata 参数已被删除，并替换为 requestBody。requestBody 更灵活，因为它允许您使用不同的媒体类型，例如 JSON、XML、表单数据、纯文本等，并为不同的媒体类型使用不同的架构。
其他重大变化包括
- 操作现在可以同时使用表单数据和其他媒体类型，例如 JSON。
- consumes 数组被 requestBody.content 映射替换，该映射将媒体类型映射到它们的架构。
- 架构可以因媒体类型而异。
- 表单数据现在可以包含对象，并且您可以为对象和数组指定序列化策略。
了解更多
阅读文档： 描述请求主体
增强的安全定义
虽然 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 还包括对 operation 参数中数组和对象的支持，并允许您指定这些参数应如何序列化。序列化方法由 style 和 explode 关键字定义
- style 定义如何分隔多个值。可能的样式取决于参数位置 - 路径、查询、标头 或 cookie。
- explode（true/false）指定数组和对象是否应为每个数组项或对象属性生成单独的参数。
OpenAPI 序列化规则基于 RFC 6570 定义的 URI 模板模式的子集。
了解更多
阅读文档： 描述参数
改进的示例
示例是记录您的 API 的重要组成部分。OAS 3.0 对示例如何在规范中使用进行了全面修改，包括描述多个示例、在 API 定义中重用示例以及引用外部示例的能力。
对示例的更改在使用示例对象时提供了更高的可重用性。
了解更多
阅读文档：添加示例
引入 OpenAPI 链接
链接是 OpenAPI 3.0 的新功能之一。链接在 API 的设计阶段引入了一个全新的概念，用于在设计 API 时显示响应和操作之间的关系。
使用链接，您可以描述一个操作返回的各种值如何用作其他操作的输入。这样，链接在操作之间提供了一种已知关系和遍历机制。链接的概念通常与超媒体进行比较，但 OpenAPI 链接不需要在实际响应中存在链接信息。
阅读文档：OpenAPI 链接
支持描述回调
OAS 3.0 提供对描述回调的支持，该回调可用于定义异步 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 资源，以帮助您入门