stoplightio / elements

Build beautiful, interactive API Docs with embeddable React or Web Components, powered by OpenAPI and Markdown.
https://stoplight.io/open-source/elements/
Apache License 2.0
1.79k stars 205 forks source link

Schema external references fail on password-protected site #2292

Open tupelo-schneck opened 1 year ago

tupelo-schneck commented 1 year ago

Context

We are trying out Stoplight Elements for API documentation, and are sharing our work-in-progress with another team on a password-protected website (HTTP Basic auth).

Current Behavior

On our password-protected site, JSON Schema external refs do not work, leading to errors in the Stoplight Elements UI like "Cannot resolve external references".

Expected Behavior

External references should work -- the site visitor has already put in the password.

Possible Workaround/Solution

We made a point change in https://github.com/APIDevTools/json-schema-ref-parser/blob/main/lib/resolvers/http.js (or rather, its minified version) to set withCredentials: true. This resolved our issue. However, it would be useful if this were the default, or else if there were some reasonable way to pass that option down from Elements.

Steps to Reproduce

Create an openapi.yml with an external $ref, like

components:
  schemas:
    User:
      $ref: './schemas/User.schema.json'

or

components:
  examples:
    UserResponse:
      summary: User
      value:
        $ref: './examples/response/user.json'

When accessing the schema, the UI shows

Example cannot be created for this schema
Error: Invalid JSON pointer: ./schemas/User.schema.json

When accessing an API which refers to that example, the UI shows

{
  "$ref": "./examples/response/user.json",
  "$error": "Cannot resolve external references"
}
tupelo-schneck commented 1 year ago

This is presumably solved by https://github.com/stoplightio/elements/pull/2006