解锁规范：默认关键字

2015年8月6日

作者：Ron Ratovksy

API 的一个常见用例是，其调用的参数可能具有预定义值。以分页为例，该调用允许您请求查询结果的特定页面。作为生产者，您可能允许消费者设置每页的条目数，但您也希望允许消费者在每次请求时无需发送预定义数量的条目。

使用默认值

这就是默认值的作用。在 Swagger 规范中，默认允许您为参数、模型（及其属性）或响应头（承载对象）设置值。当客户端或服务器省略这些值时，接收端应假定为默认值。

默认关键字的值在 Swagger 规范中略显独特。它被定义为任意类型，但旨在“复制”其承载对象的类型。因此，如果您有一个字符串类型的参数，则默认的值也应为字符串。显然，不匹配的类型没有意义，因为您将声明属性的默认值与允许的类型不同。对于复杂类型的请求体参数，默认可以表示一个复杂的默认值。数组类型的承载对象也应具有数组结构作为其默认值。

您可以在规范的以下位置找到默认属性：

为什么要使用默认值？

定义该值有以下几个好处：

如前所述，它允许从请求中省略参数/属性/头，从而简化了过程并最大限度地减少了所需的带宽。
它有助于记录 API 的行为。如果您指定了默认值，您的消费者就知道在响应中会得到什么。
它允许更好的 API 测试，因为测试人员知道未指定承载对象时预期结果是什么。

使用默认值时的常见错误

使用默认值时可能存在两种差异：

为承载对象定义默认值并将其标记为必需有些矛盾。如果承载对象是必需的，它将始终被发送，默认值将永远不会生效。
第二种情况是使用默认来提及其承载对象的示例值。这并非该字段的正确用法，可能导致某些 Swagger 工具中出现意外行为。有些承载对象提供设置示例值的替代方法。

专业提示

我们还有默认关键字的另一种用途，它非常不同。它可以在响应部分中使用，以提及 API 的通用响应。通常，您会描述成功的响应，但有时您可能有一种通用的方式来暴露错误，无论使用哪种 HTTP 状态码。在这种情况下，您可以使用默认响应并提供其使用的通用结构。

有关更多信息，请查看规范中的相关部分 - https://swagger.org.cn/specification/#responsesDefault。