Collectives™ on Stack Overflow

Find centralized, trusted content and collaborate around the technologies you use most.

Teams

Q&A for work

Connect and share knowledge within a single location that is structured and easy to search.

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:     
      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:
        description: successful operation
        schema:
          $ref: '#/definitions/AllContacts'
        description: Invalid id supplied
        description: Contact not found
        description: Server error
    definitions:
      AllContacts:
       type: array
       items:
       -  $ref: '#/definitions/ContactModel1'
       -  $ref: '#/definitions/ContactModel2'
      ContactModel1:
        type: object
        properties:
            type: integer
            example: 1
          firstName:
            type: string
            example: 'someValue'
          lastName:
            type: string
            example: 'someValue'
       ContactModel2:
        type: object
        properties:
            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.
                Do all ContactModel objects have the same field names (names, not values)? Or do they have some fields that differ?
– Helen
                Sep 12, 2017 at 14:43
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:
        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
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:
      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'
        
Thanks for contributing an answer to Stack Overflow!
Please be sure to answer the question. Provide details and share your research!
But avoid …
Asking for help, clarification, or responding to other answers.
Making statements based on opinion; back them up with references or personal experience.
To learn more, see our tips on writing great answers.