Different examples for same model in swagger

Question

I'm trying to create an example in the request portion of my Swagger file. In the (heavily simplified) snippet below my request is describing the relationship between a patient and a clinician. Both these entities use the same Identifier model.

However, I can't seem to work out how to pass in example data that would be different for the patientIdentifier and the clinicianIdentifier while still making using of the common Identifier model. The snippet I've posted is syntactically correct, but obviously in example data will be the same for both Identifiers, which is far from ideal.

I realise I can just extract the fields from the Identifer model and copy them to the patientIdentifier and clinicianIdentfier without too much effort in this case, but I'd like to know if there is a more elegant way to achieve this.

Relationship:
  properties:
    patientIdentifier:
      $ref: '#/definitions/Identifier'
    clinicianIdentifier:
      $ref: '#/definitions/Identifier'

Identifier:
  type: object
  properties:
    id:
      type: string
      example: "Jane Doe"
    group:
      type: string
      example: "WD7"

If someone could point me in the right direction with something along the lines of documentation or an example that does this, it would be really appreciated.

Thanks!

Answer 1

You'll need to provide a schema-level example for Relationship. Schema-level examples take precedence over property-level examples.

Relationship:
  type: object
  properties:
    patientIdentifier:
      $ref: '#/definitions/Identifier'
    clinicianIdentifier:
      $ref: '#/definitions/Identifier'
  example:
    patientIdentifier:
      id: Jane Doe
      group: WD7
    clinicianIdentifier:
      id: Bob Smith
      group: ABCDE

Note that property-level examples for patientIdentifier and clinicianIdentifier won't work because when using a $ref, any siblings of a $ref are ignored.

# This won't work - examples will be ignored

Relationship:
  type: object
  properties:
    patientIdentifier:

      $ref: '#/definitions/Identifier'
      example:
        id: Jane Doe
        group: WD7

    clinicianIdentifier:

      $ref: '#/definitions/Identifier'
      example:
        id: Bob Smith
        group: ABCDE