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.

Solution 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

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

Comments

[Helen]

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

[Krishna Adhikari]

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

[Daniel]

you rock! Thank you.