swagger-api / swagger-api/swagger-ui

Query parameter of type array with object $ref items renders as JSON editor instead of dynamic form rows

Open
#10,962 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: [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
Image
Additional context or thoughts

It could be related to #2707

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.