Hacktoberfest 2026: le issue che i maintainer hanno segnato per ottobre, aperte e adatte ai principianti. Sfoglia le issue Hacktoberfest

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

Aperta Adatta ai principianti
  • Qualcosa non va?
#8,690 0 commenti 0 reazioni 0 assegnatari Vedi su GitHub

I maintainer di solito rispondono entro 1 giorno

Nessuno ha ancora preso questa issue.

Valutazione

Difficoltà
2/5
Tempo stimato
1-3 ore
Idoneità per principianti
72/100
Tipo di issue
Bug
Chiarezza
Specificata chiaramente
Stato di attività
Attiva
Stack tecnologico
php
Ambito
api

Direzione di ricerca

La retrocompatibilità con la 3.0.0 si trova in LegacyOpenApiNormalizer::normalize(), che imposta la versione e retrocede schemi, percorsi e parametri, ma lascia invariate le chiavi di primo livello. OpenApiFactory fornisce sempre webhooks, e OpenApiNormalizer mantiene gli oggetti vuoti, motivo per cui webhooks: {} finisce nell'output. Per confermarlo, esegui bin/console api:openapi:export --spec-version=3.0.0. Il lavoro è completo quando l'export non contiene chiavi di primo livello della 3.1+ e supera ancora un validatore 3.0.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

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
Lingua principale
PHP
Stelle
2.6k
Fork
989
Merge medio
2g 4h
PR unite (30g)
90

Preparare l'ambiente

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di api-platform/core

Tutte le issue di api-platform/core

Issue simili

Altre issue su PHP

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.