如何在 OAS3 中记录计算的默认值

Question

我正在更新我的 API 规范 (OAS 3.0.0)，但我无法理解如何正确建模 "complex" 默认值。

通常，参数的默认值是标量值（即字段 offset 的默认值为 0）。但是在我指定的 API 中，默认值实际上是根据其他提供的参数计算的。

例如，如果我们从示例文档中获取 Pet model，并决定所有动物都需要标记，会怎样？如果 API 的用户想要提供标签，那很好。如果不是，它将等于名称。

一种可能：

Pet:
  required:
    - id
    - name
  properties:
    id:
      type: integer
      format: int64
    name:
      type: string
    tag:
      type: string
      default: '#/components/schemas/Pet/name'

这将路径值存储为默认值，但我想让它解释一下将计算默认值。

如果我可以对来自父模式的信息进行编码，则会加分。

是否可以仅在描述字段中描述行为？

Answer 1

OpenAPI 规范 does not support dynamic/conditional 默认值。您只能在 description.

中口头记录行为

也就是说，您可以使用规范扩展 (x-...) 将自定义信息添加到您的定义中，如下所示：

tag:
  type: string
  x-default: name

或

tag:
  type: string
  x-default:
    propertyName: name

# or similar

并扩展工具以支持您的自定义扩展。

如何在 OAS3 中记录计算的默认值

How to note a calculated default value in OAS3

openapi