如何在 SwaggerHub 中返回一组对象? [英] How to return an array of objects in SwaggerHub?

问题描述

我正在使用 OpenAPI 2.0 在 SwaggerHub 中定义 API 规范./contacts 请求返回一个联系人数组.定义如下:

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.

我正在使用 OpenAPI 2.0 并怀疑此版本对数组的支持不佳.

I am using OpenAPI 2.0 and suspect that the arrays are not well supported in this version.

推荐答案

对象数组定义如下.items 的值必须是描述数组项的单个模型.

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

默认情况下，Swagger UI 仅显示一项的数组示例，如下所示:

By default, Swagger UI displays the array examples with just one item, like so:

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

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

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

这篇关于如何在 SwaggerHub 中返回一组对象?的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！