Hacktoberfest 2026: le issue che i maintainer hanno segnato per ottobre, aperte e adatte ai principianti. Sfoglia le issue Hacktoberfest

Patch releases 4.4.3 / 5.0.2 change the OpenAPI document of array query parameters (#8600), duplicating `key[]` into `key[][]`

Aperta
  • Qualcosa non va?
#8,634 0 commenti 0 reazioni 0 assegnatari Vedi su GitHub

I maintainer di solito rispondono entro 1 giorno

Nessuno ha ancora preso questa issue.

Valutazione

Difficoltà
4/5
Tempo stimato
3-5 giorni
Idoneità per principianti
48/100
Tipo di issue
Bug
Chiarezza
Abbastanza chiara
Stato di attività
Attiva
Stack tecnologico
openapi, php
Ambito
api

Direzione di ricerca

Start by reading OpenApiFactory::collectPaths() and reproduce the reported output with the two QueryParameter definitions. Check the existing OpenAPI tests for array query parameters and compare the generated parameters for keys with and without [] across the affected versions. Done means the generated document avoids the unintended duplicate variant while preserving the intended parameter behavior.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

API Platform version(s) affected: 4.4.3 and 5.0.2 (api-platform/openapi), compared with 4.4.2 and 5.0.1

Description

#8600 (fixing #8421) changed how OpenApiFactory documents a filterless QueryParameter whose schema is type: array: when castToArray is not set, it now documents the parameter twice, as key and as key[] (the latter with style: deepObject, explode: true).

This shipped in patch releases and changes the generated OpenAPI document of any application with such a parameter:

  1. Every filterless array parameter gains a second documented parameter (ids → ids + ids[]).
  2. When the key already ends with [] (a common way to document the ids[]=1&ids[]=2 form the server parses), the added parameter is key[][], which the server never accepts (status[] → status[] + status[][]).

The 4.4.3 changelog lists #8600 under "Bug fixes", with no warning. The 5.0.2 changelog explains that #8598 was reverted from 4.4 because "a schema change must not ship in a patch release". #8600 is a schema change of the same kind.

How to reproduce

#[ApiResource(
    operations: [
        new GetCollection(
            uriTemplate: '/repro',
            parameters: [
                'status[]' => new QueryParameter(
                    schema: ['type' => 'array', 'items' => ['type' => 'string']],
                    required: false,
                ),
                'ids' => new QueryParameter(
                    schema: ['type' => 'array', 'items' => ['type' => 'string']],
                    required: false,
                ),
            ],
        ),
    ],
)]
final class ReproResource
{
    public ?string $id = null;
}

bin/console api:openapi:export, parameters of GET /api/repro (name, style):

api-platform/openapi Documented parameters
4.4.2, 5.0.1 status[] (form), ids (form)
4.4.3, 5.0.2 status[] (form), status[][] (deepObject), ids (form), ids[] (deepObject)

In our application the 4.4.3 bump adds 421 parameters across 16 operations. The runtime behaviour is unchanged, but:

  • generated clients change: Orval 8.39 adds a 'status[][]'? property next to 'status[]'? on every params type;
  • a CI check comparing the committed OpenAPI document with a fresh export fails on a routine Dependabot patch bump.

Possible Solution

  • Revert #8600 from 4.4, as was done for #8598, and keep it in 5.x documented as a behaviour change.
  • In any case, do not emit the key[] variant when the key already ends with [], e.g. in OpenApiFactory::collectPaths() (untested suggestion):
$canSplitToArray = null === $linkParameter
    && 'query' === $in
    && 'array' === ($parameterSchema['type'] ?? null)
    && !str_ends_with($key, '[]');

Additional Context

Workaround: set castToArray: false on these parameters. The document then lists the key as written only (status[]). It has no runtime effect: in 4.4.3 and 5.0.2, ParameterParserTrait and ParameterValidationConstraints only act on castToArray: true.

Removing the brackets from the keys and setting castToArray: true also documents key[] only, but it changes runtime behaviour: a scalar value (status=lost) is then cast to an array and accepted, where it was rejected with a 422 before.

Lingua principale
PHP
Stelle
2.6k
Fork
984
Merge medio
1g 10h
PR unite (30g)
88

Preparare l'ambiente

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di api-platform/core

Tutte le issue di api-platform/core

Issue simili

Altre issue su PHP

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.