Redocly / Redocly/redoc

<SchemaDefinition> do not work with remote reference

Open
#1,128 6 comments 10 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

investigation Type: Bug Type: Enhancement under consideration
Dominant language
TypeScript
Stars
25.9k
Forks
2.4k
Avg merge
13h 10m
Merged PRs (30d)
4

Description

This is a bug report

What happend

If <SchemaDefinition /> custom element points to remote reference, like below:

  description: 
     Blah blah blah.

     Below is `Foo` definition.
     <SchemaDefinition schemaRef="./shared-components.yaml#/components/schemas/Foo"/>

it fails with a following error:

Something went wrong...
Invalid JSON pointer: ./shared-components.yaml#/components/schemas/Foo

on versions

  • redoc@2.0.0-rc.18
  • redoc@2.0.0-rc.15

Background

I want to extract components into an external file, so it can be shared among several swagger files, like below:

  • swagger-public.yaml
  • swagger-private.yaml
  • shared-components.yaml

Remote reference feature in standard Swagger/OpenAPI syntaxes, like below, works fine 😄

  schema:
    $ref: "./shared-components.yaml#/components/schemas/Foo"

<SchemaDefinition /> works fine if used with local reference... but fails with remote reference.
So I guess this is a bug (or a limitation) of <SchemaDefinition />

A motivation I use <SchemaDefinition schemaRef="..."/> in description is to embed a component definition into some description.
Because Redoc currently does not have schemas view unlike official Swagger viewer.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reproducing the failure with the YAML example using and compare it with the working local-reference case. Trace how SchemaDefinition resolves schemaRef values, then verify that remote references resolve like the standard $ref example without breaking local references.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
api, documentation
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.