api:openapi:export --spec-version=3.0.0 outputs `webhooks`, which is invalid in OpenAPI 3.0
维护者通常 1 天内回复
评估
调研方向
降级到 3.0.0 的逻辑位于 LegacyOpenApiNormalizer::normalize()，它会设置版本并降级 schemas、paths 和 parameters，但保留顶层键不变。OpenApiFactory 始终提供 webhooks，而 OpenApiNormalizer 会保留空对象，因此 webhooks: {} 会出现在输出中。运行 bin/console api:openapi:export --spec-version=3.0.0 进行确认。完成的标准是导出结果中不含 3.1+ 的顶层键，并且仍能通过 3.0 校验器。
由索引模型根据 Issue 内容生成。
描述
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
- 主要语言
- PHP
- 星标
- 2.6k
- 派生
- 989
- 平均合并
- 2 天 2 小时
- 30 天内合并 PR
- 101
环境准备
- 没有 Dockerfile 或 Docker Compose 文件
- 有 Pull Request 模板
- 阅读贡献指南
从这里开始
- 先读完整个 Issue，再读项目的贡献指南。
- 在 Issue 下留言说明你要接手 —— 这能避免两个人做同样的事。
- Fork 仓库，在一个分支上完成修改。
- 提交 Pull Request，并在描述里引用这个 Issue 编号。
api-platform/core 的其他 Issue
-
难度 2/5 1 小时以内 新手友好度 80/100
api-platform/core#8701 ·
维护者通常 1 天内回复
-
JSON:API: `JsonApiCollectionBaseSchemaNoPagination` declares `data` as `type: array` without `items`未关闭
难度 2/5 1-3 小时 新手友好度 82/100
api-platform/core#8699 ·
维护者通常 1 天内回复
-
难度 1/5 1 小时以内 新手友好度 85/100
api-platform/core#8680 ·
维护者通常 1 天内回复
-
难度 3/5 1-2 天 新手友好度 50/100
api-platform/core#8704 ·
维护者通常 1 天内回复
-
难度 3/5 1-2 天 新手友好度 62/100
api-platform/core#8703 ·
维护者通常 1 天内回复
查看 api-platform/core 的全部 Issue
相似的 Issue
-
难度 2/5 半天 新手友好度 68/100
components-web-app/docs#244 ·
-
难度 2/5 1-3 小时 新手友好度 78/100
nhrrob/nhrrob-secure#22 ·
-
难度 2/5 1-3 小时 新手友好度 70/100
PrestaShopCorp/ps_eventbus#501 · 2 个 reaction ·
-
category::task maintenance priority::normal
难度 2/5 1-3 小时 新手友好度 62/100
e0ipso/schema-forms-php#58 ·
-
难度 2/5 1-3 小时 新手友好度 66/100
Automattic/blocks-engine#2866 ·
维护者通常 1 天内回复