Как вернуть массив объектов в SwaggerHub?

Я определяю спецификацию API в SwaggerHub, используя OpenAPI 2.0. Запрос /contacts возвращает массив контактов. Определение приведено ниже:

  /contacts:     
    get:
      tags:
      - contacts
      summary: Get all the contacts
      description: This displays all the contacts present for the user.
      operationId: getContact
      produces:
      - application/json
      - application/xml  
      responses:
       200:
        description: successful operation
        schema:
          $ref: '#/definitions/AllContacts'
       400:
        description: Invalid id supplied
       404:
        description: Contact not found
       500:
        description: Server error
    definitions:
      AllContacts:
       type: array
       items:
       -  $ref: '#/definitions/ContactModel1'
       -  $ref: '#/definitions/ContactModel2'
    
        
      ContactModel1:
        type: object
        properties:
          id:
            type: integer
            example: 1
          firstName:
            type: string
            example: 'someValue'
          lastName:
            type: string
            example: 'someValue'
            
       ContactModel2:
        type: object
        properties:
          id:
            type: integer
            example: 2
          firstName:
            type: string
            example: 'someValue1'
          lastName:
            type: string
            example: 'someValue1'

По какой-то причине он возвращает только второй объект, а не весь массив объектов.

Я использую OpenAPI 2.0 и подозреваю, что массивы плохо поддерживаются в этой версии.


openapi swagger swagger-2.0
person Krishna Adhikari    schedule 12.09.2017    source источник
comment
У всех ContactModel объектов одинаковые имена полей (имена, а не значения)? Или у них есть какие-то поля, которые отличаются?   -  person Helen    schedule 12.09.2017
comment
@Helen Все они имеют одинаковое имя поля: id, firstName и lastName.   -  person Krishna Adhikari    schedule 13.09.2017

Ответы (1)


arrow_upward
35
arrow_downward

Массив объектов определяется следующим образом. Значение items должно быть одной моделью, описывающей элементы массива.

definitions:
  AllContacts:
    type: array
    items:
      $ref: '#/definitions/ContactModel'

  ContactModel:
    type: object
    properties:
      id:
        type: integer
        example: 1
      firstName:
        type: string
        example: Sherlock
      lastName:
        type: string
        example: Holmes

По умолчанию пользовательский интерфейс Swagger отображает примеры массивов только с одним элементом, например:

[
  {
     "id": 1,
     "firstName": "Sherlock",
     "lastName": "Holmes"
  }
]

Если вы хотите, чтобы пример массива включал несколько элементов, укажите многопозиционный example в модели массива:

definitions:
  AllContacts:
    type: array
    items:
      $ref: '#/definitions/ContactModel1'
    example:
      - id: 1
        firstName: Sherlock
        lastName: Holmes
      - id: 2
        firstName: John
        lastName: Watson
person Helen    schedule 13.09.2017