Forum Discussion

warspite's avatar
warspite
New Contributor
5 years ago

Response mixing object and number in an array

I am trying to model the following structure (taken from Paypal API guidelines) into openapi 3.0.0   I have no problem getting the object users in the array, but I cannot get the total_items and to...
  • HKosova's avatar
    HKosova
    5 years ago

    "users" is an array of objects. Those individual objects are currently defined with the given_name and surname properties, but you can define additional properties as required.

     

    Maybe if you replace inline schemas with named schemas it will be easier to understand.

    paths:
  /results:
    get:
      responses:
          "200":
            description: OK
            content:
              application/json:
                schema:
                  $ref: '#/components/schemas/Results'

components:
  schemas:
    User:
      type: object
      properties:
        given_name:
          type: string
          maxLength: 50
          example: James
        surname:
          type: string
          maxLength: 50
          example: Greenwood
        ...   # <---- Define other user properties here

    Results:
      type: object
      properties:
        total_items:
          type: integer
          example: 116
        total_pages:
          type: integer
          example: 12
        users:
          description: An array of users
          type: array
          items:
            $ref: '#/components/schemas/User'
          example:
            - given_name: James
              surname: Greenwood
              ...                # <---- Add example values here
            - given_name: David
              surname: Brown
              ...                # <---- Add example values here

     

warspite's avatar
warspite
New Contributor

See below, I have already moved away from the use of Array, and now have object within object

 

 

openapi: 3.0.0
info:
  version: 1.0.0
  title: recordset
  description: recordset

servers:
  # Added by API Auto Mocking Plugin
  - description: SwaggerHub API Auto Mocking
    url: https://virtserver.swaggerhub.com/fake
 
paths:
  /results:
    get:
      responses:
          "200":
            description: OK
            content:
              application/json:
                schema:
                  type: object
                  properties:
                    total_items:
                      type: integer
                      example: 116
                    total_pages:
                      type: integer
                      example: 12
                    users:
                      type: object
                      properties:
                        given_name:
                          type: string
                          maxLength: 50
                          example: James
                        surname:
                          type: string
                          maxLength: 50
                          example: Greenwood

 

 

Which automatically provides the example

{
  "total_items": 116,
  "total_pages": 12,
  "users": {
    "given_name": "James",
    "surname": "Greenwood"
  }
}

But how to create example with 2 users?

 

HKosova's avatar
HKosova
SmartBear Alumni (Retired)
5 years ago

Try this:

                    users:
                      type: array
                      items:
                        type: object
                        properties:
                          given_name:
                            type: string
                            maxLength: 50
                            example: James
                          surname:
                            type: string
                            maxLength: 50
                            example: Greenwood
                      # Array example with multiple items
                      # Must be on the same level as `type: array`
                      example:
                        - given_name: James
                          surname: Greenwood
                        - given_name: David
                          surname: Brown
  • warspite's avatar
    warspite
    New Contributor
    5 years ago

    Thanks, i had that as well before.

     

    But next to the multiple name object (given and surname) I also need to have other items.

    Which for what I understand disqualifies the use of Array, and forces me to go to Object.

    But then I no longer can have 2 instances of the name object in the example

     

    desired output:

    {
  "total_items": 116,
  "total_pages": 12,
  "users": [{
    "given_name": "James",
    "surname": "Greenwood"
  }, {
        "given_name": "David",
         "surname": "Brown",
     }}

     

    • warspite's avatar
      warspite
      New Contributor
      5 years ago

      Think i answered it myself

       

      Object -> Array -> Object

      paths:
  /results:
    get:
      responses:
          "200":
            description: OK
            content:
              application/json:
                schema:
                  type: object
                  properties:
                    total_items:
                      type: integer
                      example: 116
                    total_pages:
                      type: integer
                      example: 12
                    users:
                      type: array
                      items:
                        type: object
                        properties:
                          given_name:
                            type: string
                            maxLength: 50
                            example: James
                          surname:
                            type: string
                            maxLength: 50
                            example: Greenwood
    • HKosova's avatar
      HKosova
      SmartBear Alumni (Retired)
      5 years ago

      "users" is an array of objects. Those individual objects are currently defined with the given_name and surname properties, but you can define additional properties as required.

       

      Maybe if you replace inline schemas with named schemas it will be easier to understand.

      paths:
  /results:
    get:
      responses:
          "200":
            description: OK
            content:
              application/json:
                schema:
                  $ref: '#/components/schemas/Results'

components:
  schemas:
    User:
      type: object
      properties:
        given_name:
          type: string
          maxLength: 50
          example: James
        surname:
          type: string
          maxLength: 50
          example: Greenwood
        ...   # <---- Define other user properties here

    Results:
      type: object
      properties:
        total_items:
          type: integer
          example: 116
        total_pages:
          type: integer
          example: 12
        users:
          description: An array of users
          type: array
          items:
            $ref: '#/components/schemas/User'
          example:
            - given_name: James
              surname: Greenwood
              ...                # <---- Add example values here
            - given_name: David
              surname: Brown
              ...                # <---- Add example values here