swagger-api / swagger-api/swagger-ui
OpenAPI 3.1.x schema with tuple restrictions on additional items throws an error and does not render.
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:
- 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/examplesdirectory, with a suitable name and updating theurl:setting indev-helpers/dev-helper-initializer.jsfile as suggested in the same previous link) - Go to
http://localhost:3200 - Click on the
/api/some-pathendpoint definition expand it. - 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:
Second error shown when clicking on the "Next >" button:
Error shown when clicking on the "x Close" button:
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
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 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