swagger-ui: Examples referenced with $ref are not rendered correctly

I would like add another argument to the case for resolution. Is the current behavior for schemas. As a developer trying to define an API, I don’t see why I can have nested schema references but not nested example references.

From my point of view, what is wrong in this example is the value key being rendered. Why can I reuse schemas but not examples?

openapi: '3.0.0'
info:
  title: 'test'
  version: '1.0.0'
paths:
  /hello:
    get:
      description: 'Get welcome message.'
      responses:
        '200':
          description: 'welcome message'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Welcome'
components:
  schemas:
    Welcome:
      type: object
      properties:
        message:
          $ref: '#/components/schemas/Message'
    Message:
      type: object
      properties:
        title:
          type: string
        info:
          type: string
      example:
        $ref: '#/components/examples/WelcomeExample'
  examples:
    WelcomeExample:
      $ref: '#/components/examples/MessageExample'
    MessageExample:
      value:
        foo: 2
        bar: 3

Encountering the same issue. Is anyone working on it?

Just trying to clarify things.

So basically we cannot use examples not only in a good way, but in fact. Because no one in their clear mind would insert a huge block of example data right in the middle of definitions - and that is exactly what we’re forced to do, because:

1. Arrays is what desperately needs loads of data,
2. but arrays can only consume example and not examples,
3. which is actually the only option to decouple definitions and data.
4. And this nonsense behavior we totally owe to some API spec, sent from above.

Did I get it right?

@webron, thanks for the response! I think there are two issues:

1. The implementation both a) resolves the $ref, and b) renders an erroneous artifact of $$ref. I think that consistency needs to be achieved. Either $refs are not supported (and displayed literally), or they are supported (in which case, rendering $$ref is a bug that needs to be fixed).
2. Since the spec isn’t explicit about the matter of resolving $refs inside examples, I would like to make a case for resolution instead of literal rendering. I think this behavior is intuitively expected by a number of users as well as some on the swagger-ui team (see @shockey’s comment in #4931). What’s the most appropriate channel through which to make such a case or feature request?

Thank you again.

@BenceSzalai

What do you think about the issue where $ref used in examples (plural, which is valid, and part of the OpenAPI specification as opposed to inside example (singular)) is dereferenced properly, but also causes an artifact of $$ref being added to the dereferenced object?

...
examples:
  Users:
    value:
      - $ref: '#/components/examples/User1/value'
      - $ref: '#/components/examples/User2/value'
...

This is not valid usage. $ref is supported only under examples.<name>, that is:

examples:
  Users:
    $ref: '#/components/examples/User1'

The value keyword is an analog of example (singular) and requires an inline example value.

Should that be opened as a separate issue than?

#5625

I am surprised to find that this ticket is closed. Using references in component examples in a similar manner to schema seems to be an intuitive and expected behaviour for many.

A list endpoint which is making use of an enveloped response becomes difficult to create an example for without duplication of the single instance example data which is required for other endpoints.

  examples:
    someResponse:
      value:
        count: 15
        next: null
        previous: null
        results:
          - $ref: '#/components/examples/exampleOne/value'
          - $ref: '#/components/examples/exampleTwo/value'

What do you think about the issue where $ref used in examples (plural, which is valid, and part of the OpenAPI specification as opposed to inside example (singular)) is dereferenced properly, but also causes an artifact of $$ref being added to the dereferenced object?

So for example this:

...
examples:
  Users:
    value:
      - $ref: '#/components/examples/User1/value'
      - $ref: '#/components/examples/User2/value'
...

Renders as this (in JSON):

[
  {
    "id": 1,
    "email": "johnd@example.com",
    "name": "John Doe",
    "$$ref": "#/components/examples/User1/value"
  },
  {
    "id": 2,
    "email": "janed@example.com",
    "name": "Jane Doe",
    "$$ref": "#/components/examples/User2/value"
  }
]

Notice the "$$ref": "#/components/examples/User*/value" as the last property. This seems to be an issue regardless what’s going on with example (singular) also mentioned in https://github.com/swagger-api/swagger-ui/issues/4924#issuecomment-428411720

Should that be opened as a separate issue than?