在Swaggerhub中返回一个对象数组

Question

我在swaggerhub中定义了一个API规范./ contacts请求返回一组联系人.定义如下:

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

由于某种原因,它只返回第二个对象而不是整个对象数组.我正在使用OpenAPI规范2.0,并怀疑此版本中的阵列不受支持

Answer 1

对象数组定义如下.值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

默认情况下,Swagger UI只显示一个项目的数组示例,如下所示:

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

如果希望数组示例包含多个项,请example在数组模型中指定多项:

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

Answer 2

我意识到这有点离题，但我来到这里寻找OpenApi 3.0的示例。对于其他正在寻找同样东西的人来说，这是如何做到的：

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'