swagger-api / swagger-api/swagger-ui

Refs from separate files are not cached

Open
#9,394 1 comment 3 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 (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:

image

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

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 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.