swagger-api / swagger-api/swagger-ui

OpenAPI 3.1.x schema with tuple restrictions on additional items throws an error and does not render.

Open
#10,921 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

Q&A (please complete the following information)
  • OS: Debian GNU/Linux 13.5 (Trixie)
  • Browser: Firefox 151.0.1 / Chromium 149.0.7827.102 (Official Build) built on Debian GNU/Linux 13 (trixie) (64-bit)
  • Method of installation: npm
  • Swagger-UI version: current HEAD in master (but the issue is also present in version 5.32.0)
  • Swagger/OpenAPI version: OpenAPI 3.1.0
Content & configuration
Minimal repro for OpenAPI definition:
{
  "openapi": "3.1.0",
  "info": {
    "title": "Minimal error reproduction",
    "version": "0.0.1"
  },
  "paths": {
    "/api/some-path": {
      "get": {
        "parameters": [
          {
            "in": "query",
            "name": "sort-by",
            "required": true,
            "schema": {
              "default": [
                [
                  "triggered-at",
                  "desc-nulls-last"
                ]
              ],
              "type": "array",
              "items": {
                "type": "array",
                "prefixItems": [
                  {
                    "type": "string",
                    "enum": [
                      "triggered-at"
                    ]
                  },
                  {
                    "type": "string",
                    "enum": [
                      "asc-nulls-first",
                      "asc-nulls-last",
                      "desc-nulls-first",
                      "desc-nulls-last"
                    ]
                  }
                ],
                "items": false
              }
            }
          }
        ],
        "summary": "Minimal repro API def",
        "tags": [
          "minimal-repro"
        ]
      }
    }
  }
}

Swagger-UI configuration options:

The default configuration used by the instructions given at https://github.com/swagger-api/swagger-ui/blob/HEAD/docs/development/setting-up.md (except for the url: setting, that points to a local file with the OpenAPI JSON file shown above).

Describe the bug you're encountering

The Swagger UI doesn't render the parameters details of the /api/some-path path, when clicked on it. It shows an error instead (see screen shots below), and displays several Javascript error and call stack traces in the Javascript console.

To reproduce

Steps to reproduce the behavior:

  1. Launch the development environment as documented at https://github.com/swagger-api/swagger-ui/blob/HEAD/docs/development/setting-up.md (after saving the OpenAPI JSON schema shown above in the dev-helpers/examples directory, with a suitable name and updating the url: setting in dev-helpers/dev-helper-initializer.js file as suggested in the same previous link)
  2. Go to http://localhost:3200
  3. Click on the /api/some-path endpoint definition expand it.
  4. See the error.
Expected behavior

The /api/some-path endpoint definition is expanded without issues, and the sort-by parameter is correctly rendered.

Screenshots

First error shown when clicking to expand the endpoint definition:

Image

Second error shown when clicking on the "Next >" button:

Image

Error shown when clicking on the "x Close" button:

Image
Additional context or thoughts

The code is blowing up at this line: https://github.com/swagger-api/swagger-ui/blob/e5d1cd3625ae35b7133742ac1035d9deb3202a27/src/core/plugins/json-schema-5/components/json-schema-components.jsx#L209

It looks like the support for JSON Schema Draft 2012-12 (the one used by OpenAPI 3.1.x) is not complete, when it comes to the tuple validation syntax, specially about the additional items in a tuple.

If we remove the final "items": false key from the tuple definition object, the Swagger UI is rendered successfully. Although the restrictions about not being able to add more entries to the tuple is not enforced (for obvious reasons).

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 at src/core/plugins/json-schema-5/components/json-schema-components.jsx around line 209, using the minimal OpenAPI JSON in dev-helpers/examples and the url setting in dev-helpers/dev-helper-initializer.js. Run the documented development environment and expand /api/some-path. Done means the sort-by parameter renders without JavaScript errors while retaining the tuple restriction from items: false.

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
Quiet
Clarity
Clearly specified
Newbie friendliness
68/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.