Issue with referenced json file example representation on SwaggerUI

[AgentSir]

Q	A
Bug or feature request?	Bug
Which Swagger/OpenAPI version?	2.0/3.0.1
Which Swagger-UI version?	3.9.3
How did you install Swagger-UI?	I use the sources locally from swagger-ui-master/dist directory
Which browser & version?	Chrome
Which operating system?	Windows 10

Demonstration API definition

{
    "swagger": "2.0",
    "openapi": "3.0.1",
...
    "responses": {
        "200": {
	    "description": "Customer.",
	        "content": {
		    "application/json": {
		        "schema": {
			    "$ref": "#/components/schemas/Customer",
			    "example": {
			        "$ref": "/assets/examples/models/customers/630432.json"
			    }
			}
		    }
		}
   	    },
...
}  

{
  "id": "630432",
  "name": "test",
  "contactId": "728867",
  "publicId": "0010339970",
  "city": "wien",
  "zipCode": "1234"
}

Expected Behavior

Swagger UI has to display my example as:

{
  "id": "630432",
  "name": "test",
  "contactId": "728867",
  "publicId": "0010339970",
  "city": "wien",
  "zipCode": "1234"
}

Current Behavior

It renders to UI as following:

{
  "id": "630432",
  "name": "test",
  "contactId": "728867",
  "publicId": "0010339970",
  "city": "wien",
  "zipCode": "1234",
  "$$ref": "/assets/examples/models/customers/630432.json"
}

Possible Solution

The issue has been already discussed there: #3638

[hkosova]

1 ) The example keyword requires an inline example, it does not support $ref.
To point to an external file containing the literal example, you need to use examples (plural) + externalValue, like so:

"content": {
  "application/json": {
    "schema": {
      "$ref": "#/components/schemas/Customer"
    },
    "examples": {
      "customer": {
        "externalValue": "/assets/examples/models/customers/630432.json"
      }
    }
  }

Please note that Swagger UI does not support examples and externalValue yet; it's tracked in #3437.

2 ) You need to remove "swagger": "2.0" from your definition because it's "openapi": "3.0.1".

The fact that $$ref is displayed is still a bug though.

[AgentSir]

Thank you for suggestions.
I found out next things:
The structure below works fine with SwaggerUI 3.9.3:

"content": {
  "application/json": {
    "schema": {
      "$ref": "#/components/schemas/Customer"
    }
  }
},
"examples": {
  "Customer": {
    "$ref": "/assets/examples/models/customers/630432.json"
  }
}

But if you try to show example as array of objects it still works wrong:

"content": {
  "application/json": {
    "schema": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/Customer"
      }
    }
  }
},
"examples": {
  "Customers": [{
    "$ref": "/assets/examples/models/customers/630432.json"
  }]
}

[heldersepu]

@AgentSir do you have a full definition you can share?
If it's large please use https://gist.github.com/ and share a link

[AgentSir]

The full definition of last code version:
https://gist.github.com/AgentSir/fef6dc84bcbc60f51e0affc2b0cccb12

[heldersepu]

There is definitely an error popping with that definition:
http://petstore.swagger.io/?docExpansion=full&url=https://gist.githubusercontent.com/AgentSir/fef6dc84bcbc60f51e0affc2b0cccb12/raw/5e9b46816606e6c2df3ad41fcb34222fb32ec82f/swagger.json
But I think the error points to something else...

To narrow down the problem can you try an examples with the $ref is on the same definition?
https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md#example-object-example

And also try with a ref to a full path like they show on the example
$ref: http://example.org/petapi-examples/openapi.json#/components/examples/name-example

[webron]

The API definition is invalid - it's a mix of 2.0 and 3.0, and not really a valid structure of either.
Please use the http://editor.swagger.io/ to check for the errors and fix them, before we can address any rendering issues.

[shockey]

Closing due to inactivity.

This is simply to keep our issue tracker clean - feel free to comment if there are any further thoughts or concerns, and we'll be happy to reopen this issue.

[erikbozic]

We're experiencing the same issue.
Using $ref in example renders the $$ref property in the UI.

Any ETA on the fix, or support for examples?

[webron]

@erikbozic it would be better to file a new ticket.

[shockey]

@erikbozic, we fixed an example $$ref issue in Friday's release, can you test with the latest version?

[erikbozic]

Yes, it now works with 3.13.0 !
Thank you!

[lock]

Locking due to inactivity.

This is done to avoid resurrecting old issues and bumping long threads with new, possibly unrelated content.

If you think you're experiencing something similar to what you've found here: please open a new issue, follow the template, and reference this issue in your report.

Thanks!