swagger-api / swagger-api/swagger-ui

"Resolve error" when definition url is relative AND the definition contains self-referencing schema

Open
#5,945 4 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

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

Description

Q&A (please complete the following information)
  • OS: Windows 10
  • Browser: Chrome
  • Version: 80.0.3987.149
  • Method of installation: npm
  • Swagger-UI version: 3.25.0
  • Swagger/OpenAPI version: OpenAPI 3.0
Content & configuration
Example Swagger/OpenAPI definition:

NOTE: The Product schema's self-referencing property. Without this the error doesn't occur.

openapi: 3.0.1
info:
  title: Test API
  version: v1
paths:
  /products:
    post:
      tags:
        - Products
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Product'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: integer
                format: int32
components:
  schemas:
    Product:
      type: object
      properties:
        id:
          type: integer
          format: int32
          readOnly: true
        description:
          type: string
          nullable: true
        parentProduct:
          $ref: '#/components/schemas/Product'
Swagger-UI configuration options:

NOTE: The relative url. If this is absolute or root-relative, the error doesn't occur.

      const ui = SwaggerUIBundle({
        url: "v1/swagger.json",
        dom_id: '#swagger-ui',
        deepLinking: true,
        presets: [
          SwaggerUIBundle.presets.apis,
          SwaggerUIStandalonePreset
        ],
        plugins: [
          SwaggerUIBundle.plugins.DownloadUrl
        ],
        layout: "StandaloneLayout"
      })
Describe the bug you're encountering

The UI displays an error (see screenshot) with the Swagger/OpenAPI definition and UI configuration shown above. I'm pretty certain it's the combination of self-referencing schema's and a "page-relative" url in the swagger-ui config that's producing this issue.

To reproduce...

Steps to reproduce the behavior:

  1. With the above definition and ui config, navigate to the UI
  2. Try to expand the Product schema in the "Schemas" section at the bottom of the UI
  3. See error
Expected behavior

No error and the schema is expanded correctly

Screenshots

screenshot

Additional context or thoughts

This is particularly problematic for cases where the Swagger/OpenAPI definition and UI are hosted together (e.g. Swashbuckle), and in a reverse-proxy / virtual directory environment.

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 issue with the provided SwaggerUIBundle configuration and OpenAPI definition, especially the relative v1/swagger.json URL and self-referencing Product schema. Inspect the schema expansion and reference-resolution path used when Product is opened. Done means the Product schema expands without an error in this setup while preserving the expected behavior for absolute and root-relative URLs.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript
Domain
frontend
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.