swagger-api / swagger-api/swagger-ui
Refs from separate files are not cached
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: 119.0.6045.160
- Method of installation: CDN
- Swagger-UI version: 5.10.0
- Swagger/OpenAPI version: OpenAPI 3.1
Content & configuration
Example Swagger/OpenAPI definition:
Spec folder:
spec/
├─ openapi.yml
├─ tray.yml
├─ common.yml
# openapi.yml
openapi: 3.1.0
servers:
- description: MyAPI
url: /api
info:
description: My Api
version: "1.0.0"
title: My Api
contact:
email: someone@somewhere.com
tags:
- name: tray
description: Tray services
/v1/tray:
$ref: "tray.yml#/tray"
/v1/tray/{tray_id}/note:
$ref: "tray.yml#/trayNote"
/v1/tray/{tray_id}/history:
$ref: "tray.yml#/trayHistory"
/v1/tray/{tray_id}:
$ref: "tray.yml#/trayById"
# tray.yml
tray:
post:
tags:
- tray
responses:
'400':
description: tray failed validation
content:
application/json:
schema:
$ref: 'common.yml#/schemas/Exception'
trayById:
get:
tags:
- tray
parameters:
- $ref: "tray.yml#/parameters/TrayId"
responses:
'400':
description: Bad request.
content:
application/json:
schema:
$ref: 'common.yml#/schemas/Exception'
put:
tags:
- tray
parameters:
- $ref: "tray.yml#/parameters/TrayId"
responses:
'400':
description: tray failed validation
content:
application/json:
schema:
$ref: 'common.yml#/schemas/Exception'
delete:
tags:
- tray
parameters:
- $ref: "tray.yml#/parameters/TrayId"
responses:
'400':
description: Bad request.
content:
application/json:
schema:
$ref: 'common.yml#/schemas/Exception'
trayNote:
get:
tags:
- tray
parameters:
- $ref: "tray.yml#/parameters/TrayId"
responses:
'400':
description: Bad request.
content:
application/json:
schema:
$ref: 'common.yml#/schemas/Exception'
post:
tags:
- tray
parameters:
- $ref: "tray.yml#/parameters/TrayId"
responses:
'400':
description: Bad request.
content:
application/json:
schema:
$ref: 'common.yml#/schemas/Exception'
trayHistory:
get:
tags:
- tray
parameters:
- $ref: "tray.yml#/parameters/TrayId"
responses:
'400':
description: Bad request.
content:
application/json:
schema:
$ref: 'common.yml#/schemas/Exception'
post:
tags:
- tray
parameters:
- $ref: "tray.yml#/parameters/TrayId"
responses:
'400':
description: Bad request.
content:
application/json:
schema:
$ref: 'common.yml#/schemas/Exception'
parameters:
TrayId:
name: tray_id
in: path
description: id of Themis tray
required: true
schema:
type: integer
# common.yml
schemas:
Exception:
type: array
items:
type: object
properties:
exception:
type: string
examples:
- ValidationException
message:
type: string
examples:
- Field Thing is not valid for some helpful reason.
field:
type: string
examples:
- thing
Swagger-UI configuration options:
<script src="https://cdnjs.cloudflare.com/ajax/libs/swagger-ui/5.10.0/swagger-ui-bundle.js"> </script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/swagger-ui/5.10.0/swagger-ui-standalone-preset.js"> </script>
<script>
window.onload = function() {
const ui = SwaggerUIBundle({
url: "http://localhost:8000/api/spec/openapi.yml",
dom_id: '#swagger-ui',
presets: [
SwaggerUIBundle.presets.apis,
SwaggerUIStandalonePreset
],
validatorUrl: null,
layout: "StandaloneLayout"
})
window.ui = ui
}
</script>
Describe the bug you're encountering
When resolving refs that point to other files, swagger-ui requests those files from the server. In the 4.x branch every file was requested exactly once. In the 5.x branch the same files are recursively requested again and again whenever a ref from the main file is resolved. The openapi spec given above yields the following network requests:
To reproduce...
Serve example openapi spec via the url argument to SwaggerUIBundle.
Expected behavior
Each individual yml file should be requested exactly once and then the cached file should be used.
Actual behavior
Each individual yml file is requested from the server whenever a ref to it is encountered.
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 loading the provided multi-file OpenAPI example through SwaggerUIBundle and inspect the network requests while resolving refs from openapi.yml, tray.yml, and common.yml. Trace the reference-resolution path responsible for repeated requests; done means each individual YAML file is requested once and subsequent refs use the cached file.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- javascript, openapi
- Domain
- frontend
- Issue type
- Bug
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 38/100