Reference definition itself is rendered to example content

[moritz-h]

Q	A
Bug or feature request?	bug
Which Swagger/OpenAPI version?	3.0.0
Which Swagger-UI version?	http://editor.swagger.io
How did you install Swagger-UI?	http://editor.swagger.io
Which browser & version?	Firefox 57 + Chrome 63
Which operating system?	Ubuntu

Demonstration API definition

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:
          type: string
      example:
        $ref: '#/components/examples/WelcomeExample'
  examples:
    WelcomeExample:
      value: {
        "message": "Hello, World!"
      }

Configuration (browser query string, constructor, config.yaml)

none using just http://editor.swagger.io

Expected Behavior

Not show the line marked in the following image.

Current Behavior

See red marker in this image:

Possible Solution

none

Context

none

[moritz-h]

Also the "value" Property is wrong "value" is part of the Definition, not part of the example content:
https://swagger.io/specification/#exampleObject

[webron]

The spec does not support references for example fields, only examples. This means that any value of example will be rendered as-is, as you can see in the UI.

As for your second comment, I didn't get what you meant.

[moritz-h]

With the second comment, I meant it should only be rendered

{
  "message": "Hello, World!"
}

and not:

{
  "value": {
    "message": "Hello, World!"
  }
}

as is thought "value" is the property name within the Example Object definition and not part of the example data. But with your answer, that everything is rendered as-is, this makes sense.

But for the first question I still think this is a rendering issue. When the reference is not interpreted than I would expect this content:

{
  "$ref": "#/components/schemas/Welcome"
}

When the reference is interpreted and "executed" I would expect this:

{
  "value": {
    "message": "Hello, World!"
  }
}

But actually rendered is this, so the reference is "executed" but also the reference definition is shown.

{
  "value": {
    "message": "Hello, World!"
  },
  "$$ref": "#/components/examples/WelcomeExample"
}

[webron]

Heh, yeah, I blame @shockey for that.

[shockey]

Hmm, yeah - this is probably something that moved around with the Swagger-Client resolver. $$ref is used internally to tell where a value came from once everything has been resolved.

Should be a simple fix 😄

[shockey]

Fixed!

[alexgmin]

This is only fixed is the $$ref key is in the first level. This example shows the ref key.

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:
          type: string
      example:
        a:
          $ref: '#/components/examples/WelcomeExample'
  examples:
    WelcomeExample:
      value: {
        "message": "Hello, World!"
      }

[shockey]

@alexgmin thanks for the heads up on that! I just merged a fix for that as well.

[krishamoud]

I'm having this issue with an array of $refs
OAI/OpenAPI-Specification#1658