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 total_pages into the array without getting indent error (tried all the indent levels) and have failed to find an example

 

So any help/example would be appreciated

{
    "total_items": "166",
    "total_pages": "83",
    "users": [
    {
        "given_name": "James",
        "surname": "Greenwood",
        ...
        "links": [
            {
                "href": "https://api.foo.com/v1/customer/users/ALT-JFWXHGUV7VI",
                "rel": "self"
            }
        ]
    },
    {
        "given_name": "David",
        "surname": "Brown",
        ...
        "links": [
            {
                "href": "https://api.foo.com/v1/customer/users/ALT-MDFSKFGIFJ86DSF",
                "rel": "self"
            }
   },
   ...
}

 

  • 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

     

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

    Hi warspite, can you please post your current YAML definition that is giving you errors?

    • warspite's avatar
      warspite
      New Contributor
      5 years ago

      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