IBX-10396: Added support for x-ibexa-example-file in request files

[mnocon]

JIRA: https://ibexa.atlassian.net/browse/IBX-10396

Current issue: request examples are not part of the REST reference, only the schema is there.

See https://doc.ibexa.co/en/5.0/api/rest_api/rest_api_reference/rest_api_reference.html#tag/Discounts/operation/api_discounts_post for an example - the schema is not that helpful when preparing a request that's more complex.

Disclaimer: I've used Copilot when writing this, especially the tests, but I've reviewed the code manually, and verified locally that it works. The tests are probably too verbose, but I'll leave the decision what to do with them up to you.

Results:

openapi_after.yaml
openapi_before.yaml

In built-in Swagger:

It also works with the buit-in Swagger doc, for both XML and JSON requests.

[mnocon]

@konradoboza I've applied your suggestions in 12a1118

In 0de53ef I'm adding improved error handling, because trying to run the OpenAPI generator failed.

The result was:

~/Desktop/Sites/v5 main +3 !200 ?29 ❯ rm -rf var/cache && php bin/console ibexa:openapi --yaml --output=test_new.yaml -v                                                                        14s  24.4.0 15:29:34

In OpenApiFactory.php line 228:

  [RuntimeException]
  Failed to parse JSON example file: /Users/marek/Desktop/Sites/v5/vendor/ibexa/collaboration/src/bundle/Resources/api_platform/examples/collaboration/POST/InvitationCreate.json.example

Hence a new PR was created: https://github.com/ibexa/collaboration/pull/105

The API file generated with the current version of the code is here:
https://gist.github.com/mnocon/7117aaf0b4d6f01047f492b40d41463b

and I need to look at PHPStan, doing it right now - done in 089715b

[alongosz]

@mnocon SonarCloud report is relevant to the changes and valid. I also wonder if OpenApiFactory itself could be refactored to reuse common parts when processing example files.

[sonarqubecloud]

Quality Gate passed

Issues
3 New issues
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

[mnocon]

@alongosz thank you for these suggestions 🙇

I've refactored the tests in d63b262 and extracted the example loading in 2c83d1f

[adriendupuis]

Not much to say about it. That's good.

[sonarqubecloud]

Quality Gate passed

Issues
3 New issues
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