Examples referencing other examples

[mcrobbj]

So for example I have an example address which I want to refrence in an example customer:

components:

  examples:
  
    address:
      summary: Address example
      value:
          address1: 41 Main Street
          address2: Morningside
          address3: Edinburgh
          address4: Lothian
          postCode: EH21 8TF
          
    customerArrayExample1:
      summary: An array of 1 customer
      value:
        total: 1
        page: 1
        pageSize: 1
        customers:
          - id: "123e4567-e89b-12d3-a456-426614174000"
            firstName: "John"
            lastName: "Doe"
            email: "[email protected]"
            phone: "+1234567890"
            address:
              $ref: '#/components/examples/address'

This is accepted, however in Swagger Editor it appears as

{
  "total": 1,
  "page": 1,
  "pageSize": 1,
  "customers": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "firstName": "John",
      "lastName": "Doe",
      "email": "[email protected]",
      "phone": "+1234567890",
      "address": {
        "$ref": "#/components/examples/address"
      }
    }
  ]
}

Is this supported and if so what am I doing wrong?

{
  "total": 1,
  "page": 1,
  "pageSize": 1,
  "customers": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "firstName": "John",
      "lastName": "Doe",
      "email": "[email protected]",
      "phone": "+1234567890",
      "address": {
        "address1": "41 Main Street",
        "address2": "Morningside",
        "address3": "Edinburgh",
        "address4": "Lothian",
        "postCode": "EH21 8TF"
      }
    }
  ]
}

Is the desired result

[handrews]

@mcrobbj I hope you don't mind I formatted your examples with syntax highlighting :-)

Unfortunately this is not supported, because the example value is a literal value. In some cases, you will want a literal property $ref as part of your example, and will not want it treated as a reference. There's really no good way around this, as any escape sequence you might think up will have some literal use case, no matter how unlikely.

The way to work around this is to use the Example Object's externalValue field to point to a document that you generate separately. Then you can have a build process to assemble complex examples from re-usable components.

[handrews]

@mcrobbj I have moved this from Q&A to Enhancements in lieu of keeping #3910 open as a separate issue.