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

The Homes (and Watson) lines under EXAMPLE is missing the COLON by mistake in this question, not in my code. My appologies — Old Man Walter
– Old Man Walter, Commented Apr 17, 2018 at 3:41

Helen · Accepted Answer · 2018-10-23 13:22:14Z

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

The COLON was just an error in my question, not by actual code. I was afraid this was to be the answer. Thx

toadking · Accepted Answer · 2022-07-06 15:08:56Z

-1

Use allOf for arrays

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

answered Jul 6, 2022 at 15:08

toadking

1

Collectives™ on Stack Overflow

How to reference array item examples in OpenAPI 3?

2 Answers 2

1 Comment

Comments

Your Answer

Linked

Hot Network Questions

Collectives™ on Stack Overflow

2 Answers 2

1 Comment

Comments

Your Answer

Sign up or log in

Post as a guest

Linked

Related