External examples not working in the last version

[dbfun]

Q&A (please complete the following information)

• OS: Ubuntu 20.04.1 LTS
• Browser: Firefox 84.0, Chromium 87.0.4280.88
• Version: see above
• Method of installation: official docker image and built from sources
• Swagger-UI version: v3.38.0
• Swagger/OpenAPI version: OpenAPI 3.0

Content & configuration

Example Swagger/OpenAPI definition:

openapi: "3.0.0"
info:
  version: 1.0.0
  title: Title
servers:
  - url: http://localhost:8089


paths:

  /healthcheck:
    get:
      security: []
      tags:
        - healthcheck
      responses:
        "200":
          description: description
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: string
                    default: ok
              examples:
                example1:
                  value:
                    $ref: "./examples/ok.json"

Swagger-UI configuration options: no

docker-compose.yml:

  swagger:
    image: swaggerapi/swagger-ui
    container_name: swagger-docs
    volumes:
      - ./docs/openapi:/srv
    environment:
      - SWAGGER_JSON=/srv/api.yaml
    restart: always
    ports:
      - ${SWAGGER_PORT}:8080
    networks:
      - frontend

To reproduce...

Steps to reproduce the behavior:

1. Place api.yaml with external examples ($ref: "./examples/ok.json")
2. Run docker container
3. Open Swagger and see the result:

{
  "$ref": "./examples/ok.json"
}

without content of the file (./examples/ok.json).

I build swagger:v3.37.1 from repo - no problem. When I use official docker image or build from sourcesswagger: v3.38.0 - has problem.

Expected behavior

I expected to see the file content like this:

{
  "result": "ok",
  "$$ref": "examples/examples/ok.json"
}

but got this:

{
  "$ref": "./examples/ok.json"
}

[mathis-m]

@hkosova could be related to #6628

[hkosova]

This change was a bug fix to stop resolving $refs in places where $refs are not actually supported, such as inside value.

@dbfun To use the content of an external file as an example value, you must use externalValue.

              examples:
                example1:
                  externalValue: "./examples/ok.json"

However, support for externalValue is not available in Swagger UI yet, this is tracked in #5433.

Please also note that relative externalValue URLs are resolved against the servers[].url rather than the OpenAPI file location.

For now, we recommend that you keep the example values in the spec itself:

              examples:
                example1:
                  $ref: '#/components/examples/example1'

components:
  examples:
    example1:
      value:
        result: ok    # <--- Example value