swagger-api / swagger-api/swagger-ui
Query parameter of type array with object $ref items renders as JSON editor instead of dynamic form rows
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]
- Browser: [Chrome]
- Swagger-UI version: [5.32.8]
- Swagger/OpenAPI version: [3.0]
Description
When an OpenAPI 3.0 operation defines a query parameter with style: form, explode: true, and a schema of type: array whose items is a $ref to an object schema, Swagger UI renders the parameter as a single JSON text editor instead of a dynamic list of form rows with individual fields per object property.
Example Swagger/OpenAPI definition:
{
"name": "Custom",
"in": "query",
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Presentation.Dtos.Customers.Requests.CustomQuery"
},
"nullable": true
}
}
"Presentation.Dtos.Customers.Requests.CustomQuery": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"format": "int32"
},
"value": {
"type": "string",
"nullable": true
}
},
"additionalProperties": false
}
Describe the bug you're encountering
The parameter renders as a JSON textarea. The user must type raw JSON to interact with it at all. The submitted request does not use bracket notation, making the parameter unusable against servers that expect it.
Expected behavior
Swagger UI should render an "Add item" button that, for each added item, expands the object properties as individual labelled input fields — consistent with how it handles array of primitives (string/integer) today, but applied recursively to object properties.
The resulting query string sent by Swagger UI should follow the indexed bracket notation that most server frameworks (e.g. ASP.NET Core, Express with qs) expect:
?Custom[0].Id=1&Custom[0].Value=foo&Custom[1].Id=2&Custom[1].Value=bar
Screenshots
Additional context or thoughts
It could be related to #2707
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 reproducing the issue in Swagger UI 5.32.8 with the supplied OpenAPI 3.0 parameter definition, then trace the parameter rendering and query serialization paths. Done means the referenced object array offers dynamic item rows with labelled properties and submits indexed bracket notation such as Custom[0].Id and Custom[0].Value.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- javascript, openapi
- Domain
- api, frontend
- Issue type
- Bug
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 52/100