Пример данных, унаследованных Open API

Я использую OpenAPI 3.0 для определения API для сервиса, который я создаю. Я столкнулся с проблемой повторного использования компонентов схемы внутри других компонентов. Например, у меня есть объект Note, который содержит объект Profile человека, создавшего заметку. Это работает, как и ожидалось, при ссылке на объект Profile с использованием ключевого слова $ref. Проблема заключается в том, что при показе примера нет никаких данных для профиля, и если я помещаю ссылку в пример, как показано ниже, он включает фактический блок OpenAPI Profile, а не только данные примера для компонента Profile.

Мне интересно, есть ли способ повторного использования компонентов в других компонентах, а также повторного использования набора примеров для этих компонентов?

Пример:

FullNote:
  allOf:
    - $ref: '#/components/schemas/BaseNote'
    - type: object
      title: A single note response
      required:
      - id
      - dateCreated
      - profile
      properties:
        id:
          type: integer
          format: int32
        dateCreated:
          type: integer
          format: int64
        profile:
          type: object
          $ref: '#/components/schemas/Profile'
      example:
        id: 123456789
        dateCreated: 1509048083045
        profile:
          $ref: '#/components/schemas/Profile'

yaml openapi swagger api-design
person Bobbake4    schedule 04.12.2017    source источник
comment
Тот же вопрос, но об OpenAPI/Swagger 2.0: Как использовать $ref в примерах ответов в Swagger?   -  person Helen    schedule 04.12.2017

Ответы (1)


arrow_upward
3
arrow_downward

Ключевое слово example (не путать с exampleS) НЕ поддерживает $ref. Весь пример должен быть указан как встроенный:

    FullNote:
      allOf:
        - $ref: '#/components/schemas/BaseNote'
        - type: object
          ...
          example:
            id: 123456789
            dateCreated: 1509048083045
            influencer:
              prop1: value1  # <----
              prop2: value2

В качестве альтернативы вы можете использовать примеры на уровне свойств — в этом случае такие инструменты, как пользовательский интерфейс Swagger, создадут пример схемы из примеров свойств.

    FullNote:
      allOf:
        - $ref: '#/components/schemas/BaseNote'
        - type: object
          ...
          properties:
            id:
              type: integer
              format: int32
              example: 123456789      # <----
            dateCreated:
              type: integer
              format: int64
              example: 1509048083045  # <----
            profile:
              # This property will use examples from the Profile schema
              $ref: '#/components/schemas/Profile'
    Profile:
      type: object
      properties:
        prop1:
          type: string
          example: value1   # <----
person Helen    schedule 04.12.2017