Hacktoberfest 2026: los issues que los mantenedores marcaron para octubre, abiertos y aptos para principiantes. Explorar issues de Hacktoberfest

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

Cerrado
  • ¿Algo no está bien?
#8,565 0 comentarios 0 reacciones 0 asignados Ver en GitHub

Los mantenedores suelen responder en 1 día

Nadie ha tomado este issue todavía.

Evaluación

Dificultad
3/5
Tiempo estimado
1-2 días
Aptitud para principiantes
65/100
Tipo de issue
Error
Claridad
Bien especificado
Estado de actividad
Activo
Stack tecnológico
php, symfony
Área
api, backend-api-design, documentation

Línea de trabajo

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.

Escrito por el modelo de indexación a partir del texto del issue.

Descripción

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)
Lenguaje dominante
PHP
Estrellas
2.6k
Forks
987
Merge medio
1 d 7 h
PR fusionados (30 d)
84

Preparar el entorno

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de api-platform/core

Todos los issues de api-platform/core

Issues similares

Más issues de PHP

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.