Использование различных свойств моделей Swagger для сбора / подробного запроса / ответа

Я новичок в Swagger и пытаюсь определить конечные точки, у которых есть:

  • Некоторые свойства только для чтения, которые не разрешены в запросе, но отображаются в ответе
  • Некоторые свойства только для белого и скрытые, которые разрешены в запросе, но не отображаются в ответе
  • Некоторые свойства только на уровне коллекции в / resources, но некоторые другие дополнительные сведения в / resources / resource-id

Я определяю следующие модели:

  • ResourceBaseModel: сохраняет все общие свойства всех
ResourceBaseModel:
  type: object
  properties:
    shared_properties:
      type: string
  • ResourceCollectionResponse: это упаковка дополнительных свойств ответа
ResourceCollectionResponse:
  type: array
  items:
    type: object
    allOf: 
      - $ref: ResourceBaseModel
      - type: object
        properties:
          collection_normal_properties:
            type: string
          collection_read_only_properties:
            type: string
            readOnly: true
  • ResourceDetailResponse: это добавляет различные свойства для ответа
ResourceDetailResponse:
  type: object
  allOf: 
    - $ref: ResourceBaseModel
    - type: object
      properties:
        detail_normal_properties:
          type: string
        detail_read_only_properties:
          type: string
          readOnly: true

  • ResourceRequest: то же самое, добавить дополнительные свойства и свойства только для записи
ResourceRequest:
  type: object
  allOf: 
    - $ref: ResourceBaseModel
    - type: object
      properties:
        request_write_only_properties:
          type: string

Это приводит к тому, что каждая модель определяется 4 раза, и я считаю, что это неэффективно.

Итак, вот мои вопросы:

  1. Я видел дискриминатор в Swagger Spec. Должен ли я использовать это со всеми из этих расширенных моделей? По результату без использования дискриминатора результат будет таким же, как при использовании allOf.
  2. readOnly, если он определен на базовом уровне, по-прежнему отображается в пользовательском интерфейсе Swagger и требует специальной обработки или фильтрации при использовании или создании документов. Демо-данные в запросе также показывают эти свойства readOnly в запросе пользовательского интерфейса Swagger (но только модель добавила метку только для чтения). Есть ли лучшее решение, кроме того, что я пытаюсь.
  3. Только для белых, насколько мне известно, не поддерживается. Является ли определение новой модели единственным способом?

Интересно, настанет ли день, когда я смогу определить только одну модель для описания всех моделей, или вы думаете, что инновационный язык, который можно компилировать в Swagger YAML, может принести пользу всему сообществу? Нравится, как Sass / LESS строит CSS?

Спасибо за вашу помощь и понимание!


person Leon Li    schedule 06.01.2017    source источник


Ответы (1)


OpenAPI 3.0.x поддерживает только для записи, а также readOnly свойства схемы. Это должно позволить вам упростить ваши модели, allOf / discriminator не требуется.

person MikeRalphson    schedule 20.12.2017