swagger-api / swagger-api/swagger-ui

$ref pointing at the same schema causes a resolver error

Open
#5,762 6 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
JavaScript
Stars
29k
Forks
9.3k
Avg merge
2d 23h
Merged PRs (30d)
25

Description

Q&A
  • OS: macOS
  • Browser: chrome
  • Version: 79
  • Method of installation: npm swagger-ui-react
  • Swagger-UI version: 3.24.3
  • Swagger/OpenAPI version: OpenAPI 3.0
Content & configuration

I have a $ref that is a causing a resolver error (#/components/schemas/PartsOrderLine/properties/listPrice/allOf/0). The main difference I can see to other working refs is that it is pointing at the same schema, although it does not throw an error if I omit /allof/0.

I have removed as much of the spec as possible, whilst retaining the error in order to simplify the problem.

For now I have ended up manually copying the information from the $ref instead of using a $ref, but that is not ideal.

Example Swagger/OpenAPI definition:

{
  "openapi": "3.0.0",
  "paths": {
    "/parts-orders": {
      "post": {
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PartsOrder"
                }
              }
            }
          }
        }
      }
    },
    "/parts-orders/{partsOrderId}": {
      "get": {
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PartsOrder"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "PartsOrder": {
        "type": "object",
        "properties": {
          "parts": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PartsOrderLine"
            }
          }
        }
      },
      "PartsOrderLine": {
        "type": "object",
        "properties": {
          "listPrice": {
            "allOf": [
              {
                "type": "string"
              }
            ]
          },
          "orderPrice": {
            "allOf": [
              {
                "$ref": "#/components/schemas/PartsOrderLine/properties/listPrice/allOf/0"
              }
            ]
          }
        }
      }
    }
  }
}

Swagger-UI configuration options:

import spec from '../../specs/parts-orders.json';
<SwaggerUI spec={spec} />
To reproduce...

Steps to reproduce the behavior:

  1. Load this up in Create React App
  2. See the resolver error
Expected behavior

The $ref resolves correctly.

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 with the reduced OpenAPI definition in the issue and load it through the shown Create React App entry point, . Trace the resolver error for the self-referential path ending in /properties/listPrice/allOf/0; done means the $ref resolves without an error and the expected schema is displayed.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript, openapi
Domain
api
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.