ReDoc UI broken out of the box: OpenAPI version hard-coded to 3.2.0, downgrade mechanism doesn't cover 3.1 or the HTML-embedded spec

The issue is in the OpenApi class and SwaggerUiProcessor. Start by examining api-platform/openapi/OpenApi.php to see the hard-coded version. Then look at LegacyOpenApiNormalizer to understand the downgrade mechanism and SwaggerUiProcessor::process() to see how the spec is embedded. The goal is to allow a spec_version context to flow through and add support for OpenAPI 3.1.0. Test by enabling ReDoc and checking the /docs.html?ui=re_doc endpoint.

Description

Since #8350, ApiPlatform\OpenApi\OpenApi hard-codes the generated document's openapi field to 3.2.0, with no way to override it:

// api-platform/openapi/OpenApi.php
public const VERSION = '3.2.0';

private string $openapi = self::VERSION;

$openapi has no constructor parameter and no setter (getOpenapi() is the only accessor), so every generated document is unconditionally tagged 3.2.0.

ReDoc 2.x (the version currently bundled in api-platform/symfony, 2.5.2) does not support OpenAPI 3.2 and rejects the document outright with Unsupported OpenAPI version: 3.2.0 (see Redocly/redoc#2773, #2746 — ReDoc 2.x only supports 3.1/3.0/Swagger 2.0; 3.2 support is planned for the upcoming Redoc 3 engine). So /docs.html?ui=re_doc is broken out of the box on a fresh install with ReDoc enabled, whenever Swagger UI's default format negotiation resolves to 3.2.0 (i.e. always, since there's no way to change it).

There is a downgrade mechanism (spec_version context key, read from the ?spec_version= query param in DocumentationAction::__invoke()), but it has two gaps that make it useless for this case:

1. Only 3.0.0 is implemented. LegacyOpenApiNormalizer::normalize() hard-codes the check to '3.0.0' !== ($context['spec_version'] ?? null) — there's no 3.1.0 branch, even though ReDoc 2.x does support 3.1. A user hitting this can only downgrade all the way to 3.0 (losing 3.1/3.2 features), not to the version their tool actually supports.
2. It never reaches the HTML-embedded UIs. SwaggerUiProcessor::process() builds the spec embedded into the ReDoc/Swagger UI/Scalar page with a hard-coded empty context:

   'spec' => $this->normalizer->normalize($openApi, 'json', []),
   

   $context (which would carry spec_version from the request) is available as a method parameter but is never passed through here. init-redoc-ui.js then does Redoc.init(data.spec, {}, ...) against that same embedded object — it never performs a separate fetch, so there's no way for ?spec_version= on the page URL to have any effect on what ReDoc actually renders, even for the one version (3.0.0) the mechanism does support.

Steps to reproduce

1. Fresh API Platform (Symfony) install, enableReDoc: true.
2. Visit /docs.html?ui=re_doc (or /docs?ui=re_doc).
3. ReDoc fails with "Unsupported OpenAPI version: 3.2.0" — Swagger UI and Scalar on the same install render fine, since both understand 3.2.

Possible fix

• Add a 3.1.0 branch to LegacyOpenApiNormalizer (or generalize it to accept any target version it knows how to downgrade to), so installs with ReDoc 2.x enabled aren't forced all the way down to 3.0.
• Thread $context (or at least spec_version) through SwaggerUiProcessor::process()'s $this->normalizer->normalize($openApi, 'json', []) call, so the embedded HTML spec actually reflects the query param / a config default — not just the raw /docs.{_format} JSON/YAML endpoints.
• Alternatively, since ReDoc's own incompatibility is the root trigger (Redocly/redoc#2773), consider defaulting enableReDoc off when the generated document targets an OpenAPI version ReDoc is known not to support, or documenting that ReDoc + the new 3.2 default are currently incompatible out of the box.

Environment

• api-platform/core (openapi + symfony packages): v4.4.0
• Bundled ReDoc: 2.5.2 (vendor/api-platform/symfony/Bundle/Resources/public/redoc/redoc.standalone.js)