Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Appearance settings
Discussion options

mcrobbj
Jun 13, 2024

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: "john.doe@example.com"
            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": "john.doe@example.com",
      "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": "john.doe@example.com",
      "phone": "+1234567890",
      "address": {
        "address1": "41 Main Street",
        "address2": "Morningside",
        "address3": "Edinburgh",
        "address4": "Lothian",
        "postCode": "EH21 8TF"
      }
    }
  ]
}

Is the desired result
You must be logged in to vote

Replies: 2 comments · 3 replies

Comment options

handrews
Jun 13, 2024
Collaborator

@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.
You must be logged in to vote
2 replies
@handrews
Comment options

handrews Jun 14, 2024
Collaborator

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

handrews Jun 6, 2025
Collaborator

@mcrobbj I wonder if overlays could help here? As noted, the problem is that we can't support $ref inside examples because then you couldn't have examples that used properties named "$ref". But overlays modify things from outside of the main specification document, so you could use that to build up more complex examples. I think.
Comment options

mcrobbj
Jun 9, 2025
Author

You must be logged in to vote
1 reply
@handrews
Comment options

handrews Jun 9, 2025
Collaborator

@mcrobbj the problem is that there is no way to distinguish between a literal $ref in an example and a $ref that is intended to behave as a reference value. We have discussed this before several times, and the Example Object was the result.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
example obj/keywords Issues with the Example Object or exampel(s) keywords
2 participants
@mcrobbj @handrews
Morty Proxy This is a proxified and sanitized view of the page, visit original site.