$$ref appears in referenced JSON file for example

[donaldpipowitch]

Q	A
Bug or feature request?	Bug
Which Swagger/OpenAPI version?	v3
Which Swagger-UI version?	v3.1.7
How did you install Swagger-UI?	$ npm i swagger-ui-dist
Which browser & version?	Chrome 60
Which operating system?	Mac

Demonstration API definition

openapi: 3.0.0
info:
  title: Example API
  version: 1-draft

paths:
  /:
    get:
      summary: Returns foo.
      responses:
        200:
          description: |-
            The foo object.
          examples:
            application/json:
              $ref: "examples/root.json"

{
  "foo": "bar"
}

Expected Behavior

Swagger UI renders my example as:

{
  "foo": "bar"
}

Current Behavior

Swagger UI renders my example as:

{
  "foo": "bar",
  "$$ref": "examples/root.json"
}

---

Note: If I use a .yaml instead like this:

Example: |-
  {
    "foo": "bar"
  }

And write $ref: "examples/root.yaml#/Example" the example renders correctly.

[shockey]

Fixed.

Thanks for the report, @donaldpipowitch!

[donaldpipowitch]

Thank you for the fix.

[dmolesUC]

I'm still seeing this in 3.4.3:

You can see this by pasting https://github.com/raw/dmolesUC3/stash_api/153b5a25b95436df7c76ba0280ae762e3dfc337e/public/openapi.yml into the petstore.swagger.io Explore bar. Is there something wrong with my syntax?

components:
  schemas:
    root:
      type: object
      properties:
        _links:
          $ref: '#/components/schemas/hal_links'
      required:
        - _links
      example:
        $ref: examples/root.json

Or is it possibly fixed for operation examples, but not schema examples?

[webron]

According to the spec, Schema Object's example does not support a reference value. You'd have to add the example inline for it to work.

[dmolesUC]

I believe you, but can you explain what's going on in the first example of this section of the spec?

Examples Object

In an example, a JSON Reference MAY be used, with the explicit restriction...

# in a model
schemas:
  properties:
    name:
      type: string
      example:
        $ref: http://foo.bar#/examples/name-example

[dmolesUC]

It looks like "Examples Object", plural, has been removed from the 3.0.1 spec, so maybe that section was in error.

[webron]

The Examples Object was a left over in 3.0.0 - but it's not referenced anywhere inside the specification so it's not really relevant. If you look at the Schema Object, at the example field itself, that's what matters.