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

api:openapi:export --spec-version=3.0.0 outputs `webhooks`, which is invalid in OpenAPI 3.0

Abierto Apto para principiantes
  • ¿Algo no está bien?
#8,690 0 comentarios 0 reacciones 0 asignados Ver en GitHub

Los mantenedores suelen responder en 1 día

@abp002 ya está trabajando en esto.

Desde el 16/10/2026.

  • #8722 de @abp002 — abierto

Evaluación

Dificultad
2/5
Tiempo estimado
1-3 horas
Aptitud para principiantes
72/100
Tipo de issue
Error
Claridad
Bien especificado
Estado de actividad
Activo
Stack tecnológico
php
Área
api

Línea de trabajo

La degradación a 3.0.0 está en LegacyOpenApiNormalizer::normalize(), que establece la versión y degrada los esquemas, las rutas y los parámetros, pero deja intactas las claves de nivel superior. OpenApiFactory siempre aporta webhooks, y OpenApiNormalizer conserva los objetos vacíos, por eso webhooks: {} llega a la salida. Para confirmarlo, ejecuta bin/console api:openapi:export --spec-version=3.0.0. Está terminado cuando la exportación no tiene claves de nivel superior de 3.1+ y sigue pasando un validador de 3.0.

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

Descripción

When exporting with --spec-version=3.0.0, the output has "openapi": "3.0.0" but still contains "webhooks": {}. webhooks was added in OpenAPI 3.1, so strict 3.0 validators reject the document.

This affects API Platform 4.4 and 5.0 (the 4.4 LegacyOpenApiNormalizer has the same 3.0.0-only check).

Context

#8350 made the generated document default to OpenAPI 3.2.0. In #8565 the maintainers confirmed that 3.0.0 and the native version (3.2.0) are the only supported targets, and that ?spec_version=3.1.0 is not a supported downgrade target. That makes the 3.0.0 export the only way to get a document that tools without 3.2 support can read (for example openapi-generator and swagger-parser, see swagger-api/swagger-parser#2248).

#8565 asked for a concrete case where 3.0.0 does not work. This is one: the 3.0.0 export is currently not valid 3.0.

Cause

LegacyOpenApiNormalizer::normalize() only sets openapi to 3.0.0 and downgrades schemas, paths and parameters. It doesn't remove top-level keys that don't exist in 3.0. OpenApiFactory always passes a webhooks ArrayObject, and PRESERVE_EMPTY_OBJECTS is enabled in OpenApiNormalizer, so the empty object is serialized.

How to reproduce

  1. Create a minimal project with one #[ApiResource].
  2. Run bin/console api:openapi:export --spec-version=3.0.0 > docs.json
  3. Run openapi-generator generate -i docs.json -g typescript-fetch -o ./output

Actual result

Exception in thread "main" org.openapitools.codegen.SpecValidationException: There were issues with the specification.
 | Error count: 1, Warning count: 2
Errors:
        -attribute webhooks is unexpected

The tail of docs.json:

"tags": [ ... ],
"webhooks": {}
}

Expected result

A 3.0.0 export contains no 3.1+ keywords (webhooks, and probably jsonSchemaDialect) and passes validation.

Possible fix

In LegacyOpenApiNormalizer::normalize(), after the 3.0.0 check:

unset($openapi['webhooks'], $openapi['jsonSchemaDialect']);

Workaround

bin/console api:openapi:export --spec-version=3.0.0 | jq 'del(.webhooks)' > docs.json

Environment

  • api-platform/* 5.0.3 (also affects 4.4)
  • PHP 8.5.11
  • Symfony 8.1.9
  • OpenAPI Generator CLI 7.26.0
Lenguaje dominante
PHP
Estrellas
2.6k
Forks
989
Merge medio
2 d 2 h
PR fusionados (30 d)
101

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.