Hacktoberfest 2026：メンテナが10月に向けて印を付けた、オープンで初心者向けの issue。 Hacktoberfest の issue を見る

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

オープン 初心者向け
  • 何か問題がありますか？
#8,690 コメント 0 件 リアクション 0 件 担当者 0 名 GitHub で見る

メンテナーはふだん 1 日以内に返信

@abp002 がすでに取り組んでいます。

2026年10月16日 から。

  • #8722 @abp002 による — オープン

評価

難易度
2/5
見積もり時間
1〜3時間
初心者へのやさしさ
72/100
issue の種類
バグ
明瞭さ
明確に書かれている
活発さ
活発
技術スタック
php
領域
api

調査の方向性

3.0.0 へのダウングレードは LegacyOpenApiNormalizer::normalize() にあり、バージョンを設定し、スキーマ、パス、パラメータをダウングレードしますが、トップレベルのキーはそのままにします。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

  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
主要言語
PHP
スター
2.6k
フォーク
989
平均マージ
2日 2時間
マージ済み PR（30日）
101

環境構築

はじめの一歩

  1. issue を最後まで読み、次にプロジェクトのコントリビューションガイドを読みます。
  2. 着手することを issue にコメントします — 二人が同じ作業をするのを防げます。
  3. リポジトリをフォークし、ブランチを切って変更します。
  4. issue 番号を参照したプルリクエストを送ります。

api-platform/core のほかの issue

api-platform/core の issue をすべて見る

似ている issue

PHP の issue をもっと見る

新しい issue をメールで受け取る

初心者向けの GitHub issue を短くまとめたダイジェスト。