Jeff ErnstFriedman

随着 OpenAPI 规范 3.0 版本即将发布候选 Beta 版本，本系列文章旨在从技术开发人员社区 (TDC) 的角度提供对变化内容和方式的见解。第一篇文章描述了规范下一次演变的背景和基本原理，第二篇文章介绍了结构性变化，接下来的几篇文章将讨论协议、文档和其他未决事项。

请求参数

在 OpenAPI 2.0 中，请求消息中所有可能变化的部分，包括 URL 参数、标头和正文，都被描述为一组类型化参数。经验表明，将 HTTP 请求正文的描述映射到与查询和标头参数相同的元数据集中存在许多挑战。今天，让我们分解这将如何影响请求正文、内容对象和 Cookie 参数。

请求正文

已将一个新属性requestBody添加到操作对象中。作为命名属性，这提供了更好的区分，并简化了参数对象，此外，它也使得更容易描述请求正文本身。

内容对象

OpenAPI 2.0 在以下方面建立了复杂的关系：

1. 声明响应媒体类型的位置
2. 定义响应模式和示例的位置

可以在全局范围内定义多个响应媒体类型，但在操作级别可以选择性地覆盖它们。但是，这允许为每个响应对象定义一个模式，尽管可以按媒体类型定义示例，或者为每个模式定义一个示例。这使得难以为不同的媒体类型定义不同的模式，以及为不同的响应对象使用不同的媒体类型。

为了解决这个问题，内容对象引入了响应对象、媒体类型和模式之间简单关系。每个响应对象都包含一个内容类型对象，用于每个受支持的媒体类型。每个内容类型对象都具有一个模式和该媒体类型的示例数组。

还将内容对象用于请求正文，并且在描述入站有效负载方面的工作方式相同。这具有神奇的效果，消除了对produces和consumes数组的需求。目前正在讨论是否还利用内容对象来描述复杂的 URL 参数和响应标头值。

这些更改导致路径项具有以下结构

Cookie 参数

虽然 TDC 成员一致认为，虽然使用 Cookie 不是传递参数的最佳实践，但仍有足够多的人表示希望描述现有的基于 Cookie 的 API，因此值得纳入新的参数类型。

在下一篇文章中，我们将介绍将要支持的新交互模式以及一些计划对有效负载描述进行的更改。

• 第 1 部分 – 背景 以及如何参与！
• 本系列的上一篇文章：第 2 部分 – 结构性变化

• 本系列的下一篇文章：第 4 部分 – 协议和有效负载
• 第 5 部分 – 文档