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.

Do all ContactModel objects have the same field names (names, not values)? Or do they have some fields that differ? — Helen
– Helen, Commented Sep 12, 2017 at 14:43
@Helen All of them have same field name which are: id, firstName and lastName. — Krishna Adhikari
– Krishna Adhikari, Commented Sep 13, 2017 at 3:54

Helen · Accepted Answer · 2017-09-13 08:27:37Z

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

Jasper Kennis · Accepted Answer · 2021-10-12 15:12:33Z

11

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'

answered Oct 12, 2021 at 15:12

Jasper Kennis

3,0626 gold badges46 silver badges78 bronze badges

Collectives™ on Stack Overflow

How to return an array of objects in SwaggerHub?

2 Answers 2

Comments

Comments

Your Answer

Linked

Hot Network Questions

Collectives™ on Stack Overflow

2 Answers 2

Comments

Comments

Your Answer

Sign up or log in

Post as a guest

Linked

Related