IBX-12046: Described OpenAPI responses with ApiPlatform\OpenApi\Model\Response objects by ViniTou · Pull Request #245 · ibexa/rest

ViniTou · 2026-09-24T13:20:11Z

🎫 Issue	IBX-12046

Related PRs:

IBX-12045: Bumped templated-uri-bundle, lexik/jwt-authentication-bundle and api-platform/core to their PHP-configured releases #244 — the API Platform 4.2 bump; merge this PR first, then IBX-12045: Bumped templated-uri-bundle, lexik/jwt-authentication-bundle and api-platform/core to their PHP-configured releases #244 drops its $responses PHPStan baseline entries.

Description:

The REST controllers documented their OpenAPI responses as plain nested arrays in openapi: new Model\Operation(responses: [...]). API Platform 4.2 — the release that replaces its XML service configuration, needed for Symfony 8 — calls Response methods on every responses entry while building the document, so plain arrays fail with Call to a member function getDescription() on array; PHPStan also flags them (Operation::__construct() expects array<Response>|null).

All 436 response entries in 140 controllers are now Model\Response objects ('description' → description:, 'content' / 'headers' → new \ArrayObject([...])); status-code keys and the documented content are unchanged. Model\Response has the same constructor in API Platform 4.1, so this works before and after the bump.

OpenApiFactory::insertIbexaResponseExample() inlined x-ibexa-example-file (283 references in the controllers) only for plain-array responses, so it now also handles Model\Response objects — updated with withContent(), which additionally keeps their headers (the array path rebuilt the response without them). Plain arrays from third-party bundles keep working. New unit tests cover response objects with and without example files.

For QA:

No functional change — same OpenAPI document, response examples included. PHP 8.3 and 8.4 on 6.0 dependencies (API Platform 4.1): unit and integration suites exit 0, PHPStan and code style clean. With API Platform 4.2.26 installed temporarily: no $responses PHPStan errors, and the full OpenAPI document (75 paths) builds from the integration kernel without errors.

Documentation:

N/A

…\Response objects API Platform 4.2 calls Response methods (e.g. getDescription()) on every responses entry when building the OpenAPI document, so a plain array no longer works there. Converts every responses array entry across the REST controllers (and the OpenApiFactoryTest fixture) from a plain array to a new ApiPlatform\OpenApi\Model\Response instance, keeping the same description/content/headers values so the generated OpenAPI document is unchanged.

…s Response objects insertIbexaResponseExample() only handled plain-array responses, so with the responses now described as ApiPlatform\OpenApi\Model\Response objects the example files were no longer inlined. Response objects are updated with withContent(), which also keeps their headers; plain arrays (third-party bundles) keep working.

mikadamczyk · 2026-09-25T07:41:39Z

-                            '$ref' => '#/components/schemas/Session',
-                        ],
-                        'x-ibexa-example-file' => '@IbexaRestBundle/Resources/api_platform/examples/user/sessions/POST/Session.xml.example',
+            Response::HTTP_OK => new Model\Response(content: new \ArrayObject([


Could we add a description: here? Before this PR the key was missing, and OpenApiFactory used the status code 201 as the description. Now Model\Response defaults to an empty string, so the generated docs will show an empty description.

Fixed in 918666e. Added a description: in the wording of the sibling responses.

mikadamczyk · 2026-09-25T07:43:08Z

-                'content' => [
+            Response::HTTP_OK => new Model\Response(
+                description: 'If set, the list is returned in XML or JSON format.',
+                content: new \ArrayObject([


missing imports

Fixed in c5c1207. ArrayObject is now imported in every controller that uses it in the OpenAPI attributes.

mikadamczyk · 2026-09-25T08:14:26Z

-                            '$ref' => '#/components/schemas/UserGroupRefList',
-                        ],
-                        'x-ibexa-example-file' => '@IbexaRestBundle/Resources/api_platform/examples/user/users/user_id/groups/POST/UserGroupRefList.xml.example',
+            Response::HTTP_OK => new Model\Response(content: new \ArrayObject([


Could we add a description?

Fixed in 918666e. Added a description: in the wording of the sibling responses.

mikadamczyk · 2026-09-25T08:14:57Z

-                            '$ref' => '#/components/schemas/User',
-                        ],
-                        'x-ibexa-example-file' => '@IbexaRestBundle/Resources/api_platform/examples/user/users/user_id/PATCH/User.xml.example',
+            Response::HTTP_CREATED => new Model\Response(content: new \ArrayObject([


Could we add a description?

Fixed in 918666e. Added a description: in the wording of the sibling responses.

mikadamczyk · 2026-09-25T08:15:13Z

-                            '$ref' => '#/components/schemas/UserGroup',
-                        ],
-                        'x-ibexa-example-file' => '@IbexaRestBundle/Resources/api_platform/examples/user/groups/path/subgroups/POST/UserGroup.xml.example',
+            Response::HTTP_CREATED => new Model\Response(content: new \ArrayObject([


Could we add a description?

Fixed in 918666e. Added a description: in the wording of the sibling responses.

mikadamczyk · 2026-09-25T08:15:22Z

-                            '$ref' => '#/components/schemas/UserGroupList',
-                        ],
-                        'x-ibexa-example-file' => '@IbexaRestBundle/Resources/api_platform/examples/user/groups/GET/UserGroupList.xml.example',
+            Response::HTTP_OK => new Model\Response(content: new \ArrayObject([


Could we add a description?

Fixed in 918666e. Added a description: in the wording of the sibling responses.

mikadamczyk · 2026-09-25T08:15:34Z

-                            '$ref' => '#/components/schemas/UserGroupRefList',
-                        ],
-                        'x-ibexa-example-file' => '@IbexaRestBundle/Resources/api_platform/examples/user/users/user_id/groups/POST/UserGroupRefList.xml.example',
+            Response::HTTP_OK => new Model\Response(content: new \ArrayObject([


Could we add a description?

Fixed in 918666e. Added a description: in the wording of the sibling responses.

mikadamczyk · 2026-09-25T08:15:46Z

-                            '$ref' => '#/components/schemas/UserGroupRefList',
-                        ],
-                        'x-ibexa-example-file' => '@IbexaRestBundle/Resources/api_platform/examples/user/users/user_id/groups/POST/UserGroupRefList.xml.example',
+            Response::HTTP_OK => new Model\Response(content: new \ArrayObject([


Could we add a description?

Fixed in 918666e. Added a description: in the wording of the sibling responses.

sonarqubecloud · 2026-09-25T08:45:37Z

Quality Gate passed

Issues
1 New issue
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

ViniTou added 2 commits September 24, 2026 15:18

konradoboza approved these changes Sep 24, 2026

View reviewed changes

mikadamczyk approved these changes Sep 25, 2026

View reviewed changes

ViniTou added 2 commits September 25, 2026 10:18

IBX-12046: Imported ArrayObject in the OpenAPI operation attributes

c5c1207

IBX-12046: Added descriptions to OpenAPI responses that had only content

918666e

ViniTou merged commit db1b5e0 into 6.0 Sep 25, 2026
9 checks passed

ViniTou deleted the IBX-12046-openapi-response-objects branch September 25, 2026 09:00

Conversation

ViniTou commented Sep 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Related PRs:

Description:

For QA:

Documentation:

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sonarqubecloud Bot commented Sep 25, 2026

Quality Gate passed

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

ViniTou commented Sep 24, 2026 •

edited

Loading