Как создать поле в определении, которое требуется для некоторых операций, а не для других

Я пишу свое определение swagger в yaml. Скажем, у меня есть определение, которое выглядит примерно так.

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?

Ответ 1

Вам нужно будет определить модели отдельно.

Однако у вас есть варианты для случаев исключения и различия.

Если вы хотите исключить, что является простым случаем, создайте модель с исключенным свойством, скажем ModelA. Затем определите ModelB как ModelA плюс дополнительное свойство:

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

Если вы хотите определить разницу, выполните тот же метод выше и исключите id из ModelA. Затем определите ModelB и ModelC как расширение ModelA и добавьте к ним свойство id, каждое из которых имеет свои собственные ограничения. Имейте в виду, что JSON Schema позволяет вам следовать первоначальному примеру выше, чтобы в некоторых случаях "переопределить" определение. Однако, поскольку он не является действительно переопределяющим, и нужно понять концепции JSON Schema, чтобы лучше не делать простых ошибок, я бы порекомендовал этот путь на данный момент.