Remote Reference within Swagger UI Docker container

Q&A

• OS: Mac OS

• Browser: chrome

• Version: 87.0.4280.67 (Official Build) (x86_64)

• Method of installation: docker

• Swagger-UI version: Docker Latest

• Docker Repo - swaggerapi/swagger-ui

• Tag: latest

• Image ID: b5b17ce84c78

• Created: 3 days ago

• Swagger/OpenAPI version: OpenAPI 3.0

I'm following the documentation here for remote references and I'm
having trouble resolving them when using the provided docker image. I'm starting it with this command:

docker run -p 8081:8080 -e SWAGGER_JSON=/mnt/V2/alert-v2.yaml -v <my desktop user path>/api_specification/:/mnt swaggerapi/swagger-ui

The /api_specification/ directory has the following structure
/api_specification/V2
/api_specification/V2/alert-v2.yaml
/api_specification/Common
/api_specification/Common/alert-common.yaml

The reference which is giving me problems is when Alert-v2 references alert-common.yaml. You can see it in the code snippet below.

Alert-v2.yaml

openapi: 3.0.0
info:
  version: 1.0.0
  title: SparkPredict REST API
  description: |
    SparkPredict REST API for alert data.
paths:
  /api/test:
    $ref: '../Common/alert-common.yaml#/paths/about'
.....

alert-common.yaml

info:
  version: 1.0.0
  title: SparkPredict Common REST API
  description: |
    SparkPredict common REST API for alert data.
servers:
  - url: 'http://api.kong-test.dev.sparkpredict.com'
    description: An example server
paths:
  about:
    get:
      tags:
        - Metadata
      description: Get service-related metadata
      summary: Get service-related metadata
      responses:
....

Could you explain to me if this type of remote referencing is possible? The documentation seems to imply that it is. Perhaps I need to modify the docker command?

The error I'm experiencing is:

Resolver error at paths./api/test.$ref
Could not resolve reference: undefined undefined

Note: If I move alert-common.yaml into the same directory (V2) as alert-v2.yaml and change the ref to

  $ref: '/alert-common.yaml#/paths/about'

then everything resolves just fine. Just looking for some clarity around this. If the answer is that this isn't possible...is there a different version/tool that supports viewing remote refs?

Thank you,
Bob

Reproduce the reference resolution using the Docker command and the mounted alert-v2.yaml and alert-common.yaml files. Start by checking how the container exposes the mounted paths and how the relative ../Common/alert-common.yaml reference is resolved; done means the reference loads without the reported Resolver error.