Hacktoberfest 2026：メンテナが10月に向けて印を付けた、オープンで初心者向けの issue。 Hacktoberfest の issue を見る

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

オープン
  • 何か問題がありますか？
#8,634 コメント 1 件 リアクション 0 件 担当者 0 名 GitHub で見る

メンテナーはふだん 1 日以内に返信

まだ誰も着手していません。

評価

難易度
4/5
見積もり時間
3〜5日
初心者へのやさしさ
48/100
issue の種類
バグ
明瞭さ
おおむね明確
活発さ
活発
技術スタック
openapi, php
領域
api

調査の方向性

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.

索引モデルが issue の本文から書いたものです。

説明

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.

主要言語
PHP
スター
2.6k
フォーク
987
平均マージ
1日 8時間
マージ済み PR（30日）
90

環境構築

はじめの一歩

  1. issue を最後まで読み、次にプロジェクトのコントリビューションガイドを読みます。
  2. 着手することを issue にコメントします — 二人が同じ作業をするのを防げます。
  3. リポジトリをフォークし、ブランチを切って変更します。
  4. issue 番号を参照したプルリクエストを送ります。

api-platform/core のほかの issue

api-platform/core の issue をすべて見る

似ている issue

PHP の issue をもっと見る

新しい issue をメールで受け取る

初心者向けの GitHub issue を短くまとめたダイジェスト。