Swagger-ui: Using $ref to refer to schema that has $ref in example treats $ref as a property

[dosentmatter]

Q&A (please complete the following information)

• OS: macOS
• Browser: chrome
• Version: 66.0.3359.181
• Method of installation: homebrew
• Swagger-UI version: https://editor.swagger.io/ and
  swagger-editor-dist@^3.3.1 using swagger-ui@^3.12.0
• Swagger/OpenAPI version: OpenAPI 3.0.1

Content & configuration

Example Swagger/OpenAPI definition:

openapi: '3.0.1'
info:
  title: 'Title'
  version: 1.0.0
components:
  schemas:
    object:
      type: object
      example:
        a:
          $ref: '#/components/schemas/object/properties/a/example'
      properties:
        a:
          type: string
          example: 'aString'
paths:
  '/path':
      post:
        requestBody:
          required: true
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/object'
        responses:
          '201':
            description: 'description'

Swagger-UI configuration options:

I don't know the configuration. This bug happens on https://editor.swagger.io/ and also on swagger-ui-watcher.

Describe the bug you're encountering

To reproduce...

Steps to reproduce the behavior:

1. Go to https://editor.swagger.io/
2. Paste in the Swagger/OpenAPI definition yaml above.
3. Expand the POST /path route
4. Paste in the yaml again. This bug seems to only happen when you update the yaml. So it might be a bug with swagger-editor instead.
5. Look a the rendered swagger-ui on the right.
6. The JSON example for the request body has a bug. It treats the $ref as a property of the JSON.

This is what you should see:

{
  "a": {
    "$ref": "#/components/schemas/object/properties/a/example"
  }
}

Expected behavior

The JSON should be:

{
  "a": "aString"
}

Screenshots

Additional context or thoughts

If you go to the Model, it will show example: aString, which is correct.

If you embed the schema within the requestBody schema manually, everything works as expected:

openapi: '3.0.1'
info:
  title: 'Title'
  version: 1.0.0
components:
  schemas:
    object:
      type: object
      example:
        a:
          $ref: '#/components/schemas/object/properties/a/example'
      properties:
        a:
          type: string
          example: 'aString'
paths:
  '/path':
      post:
        requestBody:
          required: true
          content:
            application/json:
              schema:
                type: object
                example:
                  a:
                    $ref: '#/components/schemas/object/properties/a/example'
                properties:
                  a:
                    type: string
                    example: 'aString'
        responses:
          '201':
            description: 'description'

Result:

[shockey]

Hi @dosentmatter, thanks for filing an issue!

---

@webron, what should be happening here? I don't see Reference Objects mentioned in the Example Object section of the specification, but I do see $refs used in the examples. Please advise 😄

[dosentmatter]

Hey @shockey, no problem!

I just noticed that this bug only happens when you update the yaml while the POST /path is expanded and the example json is visible. So it might be a bug with swagger-editor instead. I updated the steps to reproduce the issue. If the issue is in swagger-editor, we can move the issue over there.

If you keep POST /path collapsed, update the yaml, then expand it, it works as expected.

[shockey]

ping @webron

[webron]

Sorry for the delay here. The way it works right now is as expected. As @shockey mentioned, there's no support for $ref for examples inside the Schema Object. As such, it should treat the $ref as the example itself.

[shockey]

Thanks, @webron - closing this 😄