swagger-api / swagger-api/swagger-ui
"Resolve error" when definition url is relative AND the definition contains self-referencing schema
Nobody has claimed this yet.
- 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:
- With the above definition and ui config, navigate to the UI
- Try to expand the Product schema in the "Schemas" section at the bottom of the UI
- See error
Expected behavior
No error and the schema is expanded correctly
Screenshots

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
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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