api:openapi:export --spec-version=3.0.0 outputs `webhooks`, which is invalid in OpenAPI 3.0
Les mainteneurs répondent en général sous 1 jour
Évaluation
- Difficulté
- 2/5
- Temps estimé
- 1-3 heures
- Accessibilité débutants
- 72/100
Piste de recherche
La rétrogradation vers 3.0.0 se trouve dans LegacyOpenApiNormalizer::normalize(), qui définit la version et rétrograde les schémas, les chemins et les paramètres, mais laisse intactes les clés de premier niveau. OpenApiFactory fournit toujours webhooks, et OpenApiNormalizer conserve les objets vides, ce qui explique que webhooks: {} apparaisse dans la sortie. Pour le confirmer, exécute bin/console api:openapi:export --spec-version=3.0.0. C'est terminé lorsque l'export ne contient aucune clé de premier niveau de la version 3.1+ et qu'il passe toujours un validateur 3.0.
Rédigé par le modèle d'indexation à partir du texte de l'issue.
Description
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
- Create a minimal project with one
#[ApiResource]. - Run
bin/console api:openapi:export --spec-version=3.0.0 > docs.json - 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
- Langage dominant
- PHP
- Étoiles
- 2.6k
- Forks
- 989
- Merge moyen
- 2 j 1 h
- PR mergées (30 j)
- 104
Préparer son environnement
- Aucun Dockerfile ni fichier Docker Compose
- Propose un modèle de pull request
- Lire le guide de contribution
Par où commencer
- Lisez l'issue en entier, puis le guide de contribution du projet.
- Signalez en commentaire que vous la prenez — cela évite que deux personnes fassent le même travail.
- Forkez le dépôt et travaillez sur une branche.
- Ouvrez une pull request qui référence le numéro de l'issue.
Autres issues de api-platform/core
-
JSON:API: resource schemas (`*.jsonapi`) have `properties` but no `type: object`Peut-être pris @ousamabenyounes l’a pris aujourd’hui. Ouverte
Difficulté 2/5 Moins d'une heure Accessibilité débutants 80/100
api-platform/core#8701 ·
Les mainteneurs répondent en général sous 1 jour
-
JSON:API: `JsonApiCollectionBaseSchemaNoPagination` declares `data` as `type: array` without `items`Ouverte
Difficulté 2/5 1-3 heures Accessibilité débutants 82/100
api-platform/core#8699 ·
Les mainteneurs répondent en général sous 1 jour
-
Difficulté 1/5 Moins d'une heure Accessibilité débutants 85/100
api-platform/core#8680 ·
Les mainteneurs répondent en général sous 1 jour
-
Difficulté 3/5 1-2 jours Accessibilité débutants 68/100
api-platform/core#8725 ·
Les mainteneurs répondent en général sous 1 jour
-
Difficulté 3/5 1-2 jours Accessibilité débutants 68/100
api-platform/core#8721 ·
Les mainteneurs répondent en général sous 1 jour
Toutes les issues de api-platform/core
Issues similaires
-
loginWithCustomTokenExchange() fails when an organization is configuredPeut-être pris @awss1i l’a pris aujourd’hui. Ouverte
Difficulté 2/5 1-3 heures Accessibilité débutants 65/100
auth0/auth0-PHP#883 · 1 commentaire ·
Les mainteneurs répondent en général sous 2 jours
-
type/bug
Difficulté 1/5 Moins d'une heure Accessibilité débutants 75/100
flarum/framework#5231 · 1 commentaire ·
Les mainteneurs répondent en général sous 1 jour
-
major-release
Difficulté 1/5 Moins d'une heure Accessibilité débutants 67/100
Intervention/image#1553 ·
Les mainteneurs répondent en général sous 1 jour
-
Difficulté 2/5 1-3 heures Accessibilité débutants 76/100
omegaup/omegaup#10353 · 1 commentaire ·
Les mainteneurs répondent en général sous 5 jours
-
Difficulté 2/5 1-3 heures Accessibilité débutants 61/100