How to reference array item examples in OpenAPI 3?

Question

Using this schema definition:

schemas:
  AllContacts:
    type: array
    items:
      $ref: \'#/definitions/Contact         


        

Answer 1

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