SwaggerEditor@next: Relative $ref to other documents do not resolve in the top level doc (url dereference)

[clemensv]

Q&A (please complete the following information)

• OS: Windows 11
• Browser: Edge
• Swagger-Editor version: "next"
• Swagger/OpenAPI version: 3.1.0

Content & configuration

Example Swagger/OpenAPI definition:

We are "import URL" a doc from

https://raw.githubusercontent.com/clemensv/spec-1/fix-schemas/message/schemas/xregistry_openapi_messagedefinition.json

That doc contains several $ref relative references, e.g.

 "responses": {
          "200": {
            "description": "The root document",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "xregistry_messagedefinition_registry.json"
                }
              }
            }
          }
        }

Describe the bug you're encountering

The docs are not resolved from the origin path even though they are supposed to by Open API spec.

To reproduce...

Steps to reproduce the behavior: See above

Expected behavior

When we fix up the doc like this:

 "responses": {
          "200": {
            "description": "The root document",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "https://raw.githubusercontent.com/clemensv/spec-1/fix-schemas/message/schemas/xregistry_messagedefinition_registry.json"
                }
              }
            }
          }
        }

the schema starts resolving as expected, and also pulls in further, relatively linked schemas, so it appears that the top-level import does not set the resolution context correctly.

[char0n]

@clemensv thanks for the report.

We assume that the retrievalURI is the current window.location.href because of the nature of the online editor living inside the browser.

But I can see when you import the URL via the editor you expect that the imported URL becomes retrievalURI.

This might be a bit problematic, because after the definition is imported via URL import, you can edit it and there is no way to tell that the new version of the definition is still the one that you imported (you could replaced it with Ctrl+v as well).

The safest way how to construct your definition if to use $id to avoid various issues with retrievalURI and make your definition transferable.

 "responses": {
          "200": {
            "description": "The root document",
            "content": {
              "application/json": {
                "schema": {
                  "$id": "https://raw.githubusercontent.com/clemensv/spec-1/fix-schemas/message/schemas/",
                  "$ref": "xregistry_messagedefinition_registry.json"
                }
              }
            }
          }
        }

Would that work for you?