Response mixing object and number in an array

[warspite]

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]

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

[warspite]

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]

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]

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]

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 · Accepted solution]

"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