swagger - 如何在某些操作而不是其他操作所需的定义中创建字段

Question

我正在用 yaml 编写我的 swagger 定义。假设我有一个看起来像这样的定义。

paths:
  /payloads:
    post:
      summary: create a payload
      ...
      parameters:
      - in: body
        name: payload
        description: New payload
        required: true
        schema:
          $ref: "#/definitions/payload"
    put:
      summary: update a payload
      ...
      parameters:
      - in: body
        name: payload
        description: Updated existing payload
        required: true
        schema:
          $ref: "#/definitions/payload"
...
definitions:
  payload:
    properties:
      id:
        type: string
      someProperty:
        type: string
      ...

有没有一种方法可以表明 PUT 操作需要有效载荷的 id 属性，并且对于 POST 操作是可选的(或根本不应该出现)？

Answer 1

您必须单独定义模型。

但是，您可以选择排除和差异的情况。

如果您想排除，这是一种简单的情况，请创建一个具有排除属性的模型，例如 ModelA .然后定义 ModelB如 ModelA加上额外的属性:

ModelB:
  allOf:
    - $ref: "#/definitions/ModelA"
    - type: object
      properties:
        id:
          type: string

如果您想定义差异，请按照上述相同的方法，并排除 id来自 ModelA .然后定义 ModelB和 ModelC作为扩展 ModelA并添加 id他们的属性(property)，每个人都有自己的限制。请注意，JSON Schema 可以让您在某些情况下按照上面的原始示例来“覆盖”定义。但是，由于它并不是真正的压倒一切，并且需要更好地理解 JSON Schema 的概念以免犯简单的错误，因此我建议现在走这条路。