Fixed and enhanced OpenAPI

[adriendupuis]

🎫 Issue	IBX-10444

⚠️ Don't merge, don't review, this PR is split into smaller batches for review. It's kept to host a summary of what is done and what is left to do.

Related PRs:

• Continue Fixed OpenAPI factory REST prefix and minor schema issues #169
• See "Summary" section below for way more related PRs

Description:

Accept and Content-Type headers

https://spec.openapis.org/oas/v3.1.1.html#x4-8-12-2-1-common-fixed-fields

If in is "header" and the name field is "Accept", "Content-Type" or "Authorization", the parameter definition SHALL be ignored.

https://swagger.io/docs/specification/v3_0/describing-parameters/#header-parameters

Note: Header parameters named Accept, Content-Type and Authorization are not allowed.

When using "Try it out' on live doc (/api/ibexa/v2/doc#/Objects/api_contentobjects_contentId_get), the previously displayed Accept header parameter form input was never taken into account. To choose an Accept header, one must be selected in the Responses panel.

So, I removed the useless and ignored Accept header parameter definition, and moved it's description up into the ressource description.

Other changes

• Add X-CSRF-Token header on not safe methods
• The If-None-Match header isn't required. The Response::HTTP_NOT_MODIFIED 304 description was saying the opposite of its meaning.
• Fix some 'x-ibexa-example-file' path (for example, when several example files have the same name, only the same one was used in all cases)
• Add several missing descriptions.
• Sort mime-types so JSON is before XML.
• Add operationId with route ID as value (eventually append the method when several are supported by the same route, or a param name when an optional parameter force documenting two routes)
• IBX-8356: Reworked Ibexa\Core\MVC\Symfony\Security\Authentication\AuthenticatorInterface usages to comply with Symfony-based authentication #101 removed XML support for JWT token so I removed it in JWT: The XML input and output aren't supported #217 and here.

Copilot's help

See #218 and ibexa/segmentation#167 for how I used Copilot for repetitive tasks.
Between the two, I added, for example, the mime-type sorting, more example fixing instructions, the operationId.

Summary

Package	PR	Batch	Branch	State	Comment
ibexa/rest	#228	Desc	fix-response-descriptions	Merged	Fix description overridden with status code
ibexa/rest	#217	JWT	fix-jwt-doc	Merged	Needed for MCP Server doc documentation-developer#3106
ibexa/rest	#195	0/6	enh-openapi	Draft	Split into 6 batches; WIP/TODO: BinaryContent, ContentTypeCopyController,…
ibexa/rest	#220	1/6	enh-openapi-ContentType	Merged
ibexa/rest	#221	2/6	enh-openapi-Content	Merged
ibexa/rest	#222	3/6	enh-openapi-Location-ObjectState	Merged
ibexa/rest	#223	4/6	enh-openapi-User-Session	Review
ibexa/rest	#224	5/6	enh-openapi-Role	Merged
ibexa/rest	#225	6/6	enh-openapi-misc	Merged
ibexa/rest	#231	1/1	fix-user-openapi-doc	Draft	IBX-12003
ibexa/activity-log	ibexa/activity-log#157	1/1	fix-openapi	Merged
ibexa/calendar	ibexa/calendar#92	1/1	fix-openapi	Merged
ibexa/cart	ibexa/cart#170	1/1	fix-openapi	Merged
ibexa/collaboration	ibexa/collaboration#109	1/1	fix-openapi	Review
ibexa/connect	ibexa/connect#TODO			TODO	TODO: document TemplateController
ibexa/connector-ai	ibexa/connector-ai#179	1/2	reduce_image_size	Merged	Image size
ibexa/connector-ai	ibexa/connector-ai#181	2/2	fix-openapi	Merged
ibexa/connector-dam	ibexa/connector-dam#TODO			TODO	TODO: document AssetVariationController & AssetController
ibexa/connector-qualifio	ibexa/connector-qualifio#TODO			TODO	TODO: document CampaignListController
ibexa/corporate-account	ibexa/corporate-account#359	1/1	fix-openapi	Merged
ibexa/discounts	ibexa/discounts#324	1/1	fix-openapi	Merged
ibexa/discounts-codes	ibexa/discounts-codes#47	1/1	openapi	QA	Full implementation
ibexa/integrated-help	ibexa/integrated-help#TODO			TODO	TODO: document ProductTourController
ibexa/order-management	ibexa/order-management#181	1/1	fix-openapi	Merged
ibexa/payment	ibexa/payment#195	1/1	fix-openapi	Merged
ibexa/personalization	ibexa/personalization#TODO			TODO	TODO
ibexa/product-catalog	ibexa/product-catalog#1503	1/1	fix-openapi	Merged
ibexa/segmentation	ibexa/segmentation#167	1/1	fix-openapi	Merged	Prompt in description
ibexa/share	ibexa/share#TODO			TODO	TODO: document UsersWithPermissionInfoController
ibexa/shipping	ibexa/shipping#144	1/1	fix-openapi	Merged	Document ShipmentCreateController, format the others
ibexa/shopping-list	ibexa/shopping-list#61	1/1	fix-openapi	Merged	Minor changes
ibexa/taxonomy	ibexa/taxonomy#412	1/1	fix-openapi	Merged

ibexa/documentation-developer#3194 removes the script forcing JSON before XML as it won't be needed anymore.

For QA:

You can generate the specification and user other tools to check it.

php bin/console ibexa:openapi --yaml

Pasted in SwaggerEditor: only report warnings about GET routes with payloads:
requestBody does not have well-defined semantics for GET, HEAD and DELETE operations

Using Redocly CLI lint command several errors are reported.
You can compare with and without the fixes to see many errors disappearing. I ignore several rules for now. I use JSON output to not have line numbers and ease the comparison between the outputs without/with the fixes.

php bin/console ibexa:openapi --yaml > openapi.yaml

redocly lint openapi.yaml --format=json --extends=recommended \
    --skip-rule=no-identical-paths \
    --skip-rule=no-ambiguous-paths \
    --skip-rule=operation-4xx-response \
    --skip-rule=no-invalid-media-type-examples \
    --skip-rule=info-license \
    --skip-rule=tag-description \
    --skip-rule=no-unused-components \
    --skip-rule=operation-2xx-response \
> redocly-lint.fixed.json

Documentation:

[sonarqubecloud]

Quality Gate passed

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

[sonarqubecloud]

Quality Gate passed

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

[sonarqubecloud]

Quality Gate passed

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

[sonarqubecloud]

Quality Gate passed

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

[sonarqubecloud]

Quality Gate passed

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

[sonarqubecloud]

Quality Gate passed

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