How to reference array item examples in OpenAPI 3?

Question

Using this schema definition:

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

I get this expected result:

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

Now I'd like to reuse the Holmes example for both the single user (ContactModel1) and as part of an array of users (AllContacts). But if I use the referenced examples:

schemas:

  AllContacts:
    type: array
    items:
      $ref: '#/definitions/ContactModel1'
    example:
      Homes:
        $ref: '#/components/examples/Homes'
      Watson:
        $ref: '#/components/examples/Watson'

  examples:

    Holmes:
      value:
        id: 1
        first_name: Sherlock
        last_name: Holmes

    Watson:
      value:
        id: 2
        first_name: John
        last_name: Watson

I get this unexpected result in Swagger UI:

[
  {
    "value": {
      "id": 1,
      "first_name": "Sherlock",
      "last_name": "Holmes",
    },
    "$$ref": "#/components/examples/Holmes"
  },
  {
    "value": {
      "id": 2,
      "first_name": "John",
      "last_name": "Watson",
    },
    "$$ref": "#/components/examples/Watson"
  }
]

and a similar unexpected example for GET /user/1:

[
  {
    "value": {
      "id": 1,
      "first_name": "Sherlock",
      "last_name": "Holmes",
    },
    "$$ref": "#/components/examples/Holmes"
  }
]

What am I doing wrong?

I am using this doc as reference:
https://swagger.io/docs/specification/adding-examples/#reuse

Solution

This is NOT a valid definition:

components:
  schemas:
    AllContacts:
      type: array
      items:
        $ref: '#/definitions/ContactModel1'
      example:
        Homes:
          $ref: '#/components/examples/Homes'
        Watson:
          $ref: '#/components/examples/Watson'

1) The example syntax is wrong. OpenAPI 3.0 has two keywords for examples - example (singular) and examples (plural). They work differently:

• example requires an inline example and does not support $ref.
• examples is a map (collection) of named examples. It supports $ref - but you can only $ref whole examples, not individual parts of an example. This also means it's not possible to build an example from multiple $refs. Note that not all elements support plural examples.

Note for Swagger UI users: Swagger UI currently supports example (singular) but not examples (plural). Support for examples is tracked in this issue.

2) The Schema Object only supports singular example but not plural examples. In other words, schemas support inline examples only.

3) In OpenAPI 3.0, schema references use the format #/components/schemas/..., not #/definitions/...

I'd like to use the same EXAMPLE definition for Holmes in both cases, the array of users and the single user.

There's no way to reuse a part of an example in this case. You'll have to repeat the example value in both schemas:

components:
  schemas:
    ContactModel1:
      type: object
      properties:
        ...
      example:
        id: 1
        first_name: Sherlock
        last_name: Holmes

    AllContacts:
      type: array
      items:
        $ref: '#/components/schemas/ContactModel1'
      example:
        - id: 1
          first_name: Sherlock
          last_name: Holmes
        - id: 2
          first_name: John
          last_name: Watson