Return an array of object in Swaggerhub

问题

I am defining an API specification in swaggerhub. 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 spec 2.0 and suspect that the arrays are not well supported in this version

回答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

来源：https://stackoverflow.com/questions/46167981/return-an-array-of-object-in-swaggerhub