OpenAPI：强制字段、可选字段和未指定字段的混合

Question

我需要指定我的端点有一个必填字段、一个可选字段并对任意数量的字段开放（可以在不验证的情况下发送）。

对于例如端点/user

user_id: str, mandatory
timestamp_utc: timestamp, optional
..*accept_any_extra_fields**..

因此，如果有人将以下 json 发送到我的端点，该端点应该接受它

{ "user_id": 1,
  "name": "Sam",
  "location": "USA"
}

但如果发送以下 json 则失败，因为它不包含user_id.

{ "name": "Sam",
  "location": "USA"
}

它应该失败。

我是 OpenAPI/Swagger 的新手。我知道我可以发送额外的数据。但是我如何将其描述为 OpenAPI 上的文档，以便人（或程序）知道他们可以发送任何字段（例如名称、位置）以及user_id

Answer 1

该additionalProperties关键字允许模式具有除本properties节中列出的属性之外的额外属性。

MyModel:
  type: object
  required:
    - user_id
  properties:
    user_id:
      type: string
    timestamp_utc:
      type: string
  additionalProperties: true   # OpenAPI 3.x
  # or
  # additionalProperties: {}   # OpenAPI 2.0

实际上，在没有关键字的情况下，OpenAPI 模式默认对扩展开放additionalProperties。但是，某些工具认为缺少additionalProperties“不允许使用其他属性”，因此最好明确添加additionalProperties: true/additionalProperties: {}以防万一。

如果额外的属性仅限于特定的数据类型，例如string，使用

 additionalProperties:
   type: string