Do not resolve $refs in property examples

[hkosova]

Q&A (please complete the following information)

• OS: Windows 10
• Browser: any
• Method of installation: any
• Swagger-UI version: 3.36.2
• Swagger/OpenAPI version: 2.0, 2.0

Content & configuration

Example Swagger/OpenAPI definition:

openapi: 3.0.0
info:
  title: $ref in a property example
  version: 1.0.0

paths:
  /foo:
    get:
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MyObject'

components:
  schemas:
    MyObject:
      type: object
      properties:
        prop:
          type: object
          example:
            $ref: '#/components/examples/StringExample'

  examples:
    StringExample:
      value: test

Describe the bug you're encountering

Even though the example keyword does not support $ref, Swagger UI attempts to resolve those $refs when generating examples.

$refs should only be resolved when used directly under examples.<name> in OAS3 definitions.

Expected behavior

Response example appears as follows, with $ref treated as a literal property in the example object.

{
  "prop": {
    "$ref": "#/components/examples/StringExample"
  }
}

Actual behavior

Response example appears as

{
  "prop": {
    "value": "test"
  }
}

Additional context or thoughts

Related issues with $refs in examples:

• Do not resolve $ref in examples..value #5625 - Do not resolve $ref in examples..value
• Do not resolve $ref in OAS 2.0 response examples #4765 - Do not resolve $ref in OAS 2.0 response examples

[hkosova]

Another test case (simplified example from #4775):

openapi: 3.0.0
info:
  version: AAAAA
  title: AAAAA
paths:
  /quotations:
    post:
      responses:
        '200':
          description: OK
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/quotations'
components:
  schemas:
    quotations:
      type: object
      properties:
        stops:
          type: array
          items:
            type: object
          example:
            - remarks: Call me after arrived
            - $ref: '#/components/examples/stop1'   # <---------

  examples:
    stop1:
      value:
        remarks: Office hours from 0900 to 1800 HKT

Expected:

{
  "stops": [
    {
      "remarks": "Call me after arrived"
    },
    {
      "$ref": "#/components/examples/stop1"
    }
  ]
}

Actual:

{
  "stops": [
    {
      "remarks": "Call me after arrived"
    },
    {
      "value": {
        "remarks": "Office hours from 0900 to 1800 HKT"
      },
      "$$ref": "#/components/examples/stop1"
    }
  ]
}

[hkosova]

Same issue in the swagger-js repo: swagger-api/swagger-js#1801

[PrasannaAiluri]

Hi @hkosova
I do have an issue on similar lines swagger-api/swagger.io-docs#326
Do you have any resolution for the above?

Thanks,
Prasanna