How to return an array of objects in SwaggerHub?

Question

I am defining an API specification in SwaggerHub using OpenAPI 2.0. The /contacts request returns an array of contacts. The definition is below:

  /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'

For some reason, it only returns the second object not the whole array of objects.

I am using OpenAPI 2.0 and suspect that the arrays are not well supported in this version.

Jazzman

Do all ContactModel objects have the same field names (names, not values)? Or do they have some fields that differ? – Leafstalk

@Leafstalk All of them have same field name which are: id, firstName and lastName. – Jazzman

Answer 1

An array of objects is defined as follows. The value of items must be a single model that describes the array 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

By default, Swagger UI displays the array examples with just one item, like so:

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

If you want the array example to include multiple items, specify the multi-item example in the array model:

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

Leafstalk

Answer 2

I realise this is a bit offtopic, but I landed here looking for an example for OpenApi 3.0. For others looking for the same thing, this is how to do it:

paths:
  /product-category:
    get:
      summary: 'Returns all product categories'
      operationId: readProductCategory
      tags:
        - productCategory
      responses:
        '200':
          description: 'Details about all product categories'
          content:
            application/json:
              schema:
                type: array
                items:
                  allOf:
                    - $ref: '#/components/schemas/Identifier'
                    - $ref: '#/components/schemas/ProductCategory'

Underbred