Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

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

Open Beginner friendly
  • Is something wrong?
#8,690 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
2/5
Estimated time
1-3 hours
Newbie friendliness
72/100
Issue type
Bug
Clarity
Clearly specified
Activity status
Active
Tech stack
php
Domain
api

Research direction

The 3.0.0 downgrade lives in LegacyOpenApiNormalizer::normalize(), which sets the version and downgrades schemas, paths and parameters but leaves top-level keys alone. OpenApiFactory always supplies webhooks, and OpenApiNormalizer keeps empty objects, which is why webhooks: {} reaches the output. Run bin/console api:openapi:export --spec-version=3.0.0 to confirm. Done means the export has no 3.1+ top-level keys and still passes a 3.0 validator.

Written by the indexing model from the issue text.

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

  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
Dominant language
PHP
Stars
2.6k
Forks
989
Avg merge
2d 4h
Merged PRs (30d)
90

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from api-platform/core

All issues in api-platform/core

Similar issues

More PHP issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.