Повторное использование модели с различными требуемыми свойствами

У меня есть путь, который использует сложные модели с почти одинаковыми свойствами для каждого метода http. Проблема в том, что я хочу определить некоторые требуемые свойства для запроса PUT и POST, в то время как в ответе GET не требуются свойства (так как сервер всегда возвращает все свойства и упоминается в другом месте документации).

Я создал простой API кота, чтобы продемонстрировать, что я пробовал. Идея заключается в том, что для ответа GET модель ответа не имеет ничего, что требуется, но запрос PUT должен иметь имя для cat.

swagger: "2.0"

info:
  title: "Cat API"
  version: 1.0.0

paths:
  /cats/{id}:
    parameters:
      - name: id
        in: path
        required: true
        type: integer
    get:
      responses:
        200:
          description: Return a cat
          schema:
            $ref: "#/definitions/GetCat"
    put:
      parameters:
        - name: cat
          in: body
          required: true
          schema:
            $ref: "#/definitions/PutCat"
      responses:
        204:
          description: Cat edited

definitions:
  Cat:
    type: object
    properties:
      name:
        type: string
  GetCat:
    allOf:
      - $ref: "#/definitions/Cat"
    properties:
      id:
        type: integer
  PutCat:
    type: object
    required:
      - name
    properties:
      $ref: "#/definitions/Cat/properties"

Редактор Swagger говорит, что это допустимая спецификация, но name устанавливается как требуется для GET и PUT. То же самое происходит с интерфейсом Swagger.

Я также попробовал следующую версию PutCat:

PutCat:
  type: object
  required:
    - name
  allOf:
    - $ref: "#/definitions/Cat"

Но теперь все необязательно.

Я не могу понять это. Есть ли способ сделать это правильно?

EDIT:

Как Helen, правильно упомянутый, я могу использовать readOnly для решения этого конкретного случая с помощью GET и PUT.

Но скажем, я добавляю свойство breed, которое должно быть предоставлено (в дополнение к свойству name) для PUT. Затем я добавляю метод PATCH, который можно использовать для обновления либо breed, либо name, в то время как другой остается неизменным, и я не хочу устанавливать ни один из них по мере необходимости.

Ответы

Ответ 1

В вашем примере вы можете использовать одну модель для GET и POST/PUT со свойствами, которые используются только в ответе GET, отмеченном как readOnly. Из spec:

readOnly

Объявляет свойство "только для чтения". Это означает, что он МОЖЕТ быть отправлен как часть ответа, но НЕ ДОЛЖЕН быть отправлен как часть запроса. Свойства, помеченные как readOnly, являющиеся истинными, НЕ ДОЛЖНЫ находиться в обязательном списке определенной схемы. Значение по умолчанию - false.

Спецификация будет выглядеть так:

    get:
      responses:
        200:
          description: Return a cat
          schema:
            $ref: "#/definitions/Cat"
    put:
      parameters:
        - name: cat
          in: body
          required: true
          schema:
            $ref: "#/definitions/Cat"
      responses:
        204:
          description: Cat edited

definitions:
  Cat:
    properties:
      id:
        type: integer
        readOnly: true
      name:
        type: string
      breed:
        type: string
    required:
      - name
      - breed

Это означает, что вы должны нажать name и breed:

{
  "name": "Puss in Boots",
  "breed": "whatever"
}

и GET /cats/{id} должны возвращать name и breed и также могут возвращать id:

{
  "name": "Puss in Boots",
  "breed": "whatever",
  "id": 5
}