swagger-api / swagger-api/swagger-ui

[Bug]: Resolver error for array item refs in nested external OpenAPI documents

Open
#11,018 0 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

Describe the bug you're encountering

Swagger UI reports a resolver error when an operation is reached through an external Path Item and its request schema is in another external YAML file. The schema contains allOf/oneOf branches and an array whose items is a local $ref to an enum in that schema file.

All referenced YAML files are served successfully. Replacing the two items.$ref nodes with equivalent inline string enums removes the error, so this appears to be a resolver issue rather than an unavailable-file or invalid-schema issue.

This looks related to #5820, but this reproduction specifically requires the external Path Item -> external Schema reference chain.

Environment

  • Swagger UI: 5.32.14 (latest at the time of reporting)
  • OpenAPI: 3.0.3
  • Browser: Chromium
  • Installation: CDN assets from swagger-ui-dist@5.32.14

To reproduce

Serve the following three files from one directory, for example:

python3 -m http.server 8080

Then open http://localhost:8080/index.html.

index.html

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Swagger UI resolver reproduction</title>
  <link rel="stylesheet" href="https://unpkg.com/swagger-ui-dist@5.32.14/swagger-ui.css">
</head>
<body>
<div id="swagger-ui"></div>
<script src="https://unpkg.com/swagger-ui-dist@5.32.14/swagger-ui-bundle.js"></script>
<script src="https://unpkg.com/swagger-ui-dist@5.32.14/swagger-ui-standalone-preset.js"></script>
<script>
  window.ui = SwaggerUIBundle({
    url: 'openapi.yml',
    dom_id: '#swagger-ui',
    presets: [SwaggerUIBundle.presets.apis, SwaggerUIStandalonePreset],
    layout: 'StandaloneLayout'
  })
</script>
</body>
</html>

openapi.yml

openapi: 3.0.3
info:
  title: Chart configuration API
  version: 1.0.0
paths:
  /charts:
    $ref: './paths/charts.yml#/charts'

paths/charts.yml

charts:
  post:
    operationId: createChart
    requestBody:
      required: true
      content:
        application/json:
          schema:
            $ref: '../schemas/chart.yml#/ChartConfiguration'
    responses:
      '204':
        description: Chart created

schemas/chart.yml

ChartConfiguration:
  type: object
  additionalProperties: false
  required: [view]
  properties:
    view:
      type: string
    chartTypes:
      type: array
      items:
        $ref: '#/ChartType'
  allOf:
    - oneOf:
        - properties:
            view:
              type: string
              enum: [summary]
        - properties:
            view:
              type: string
              enum: [detail]
    - oneOf:
        - additionalProperties: true
          required: [chartTypes]
          properties:
            view:
              type: string
              enum: [summary]
            chartTypes:
              type: array
              minItems: 1
              items:
                $ref: '#/ChartType'
          allOf:
            - oneOf:
                - additionalProperties: true
                  properties:
                    includeLegend:
                      type: boolean
                      enum: [true]
                - additionalProperties: true
                  properties:
                    includeLegend:
                      type: boolean
                      enum: [false]
        - additionalProperties: true
          properties:
            view:
              type: string
              enum: [detail]

ChartType:
  type: string
  enum: [line, bar, pie]

Actual behavior

Swagger UI renders the operation but displays:

Resolver error
Cannot read properties of undefined (reading 'items')

The browser console points to applyOperation / applyPatch in swagger-ui-bundle.js.

Expected behavior

The local ChartType references in items should resolve without an error. The schema is valid OpenAPI 3.0.3, and every YAML file is accessible.

Workaround

Replacing both occurrences below with the equivalent inline schema removes all resolver errors:

items:
  type: string
  enum: [line, bar, pie]

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 running the three-file reproduction with python3 -m http.server and inspect the resolver error in swagger-ui-bundle.js, especially applyOperation and applyPatch as indicated by the browser console. Trace how the external Path Item, external schema, nested allOf/oneOf branches, and array items.$ref are processed; done means both local ChartType references resolve without an error and the operation renders normally.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript
Domain
api, frontend
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
55/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.