[BUG] Cannot parse OpenAPI 3.1 specs using $dynamicRef / $dynamicAnchor (blocked by swagger-parser)
まだ誰も着手していません。
評価
- 難易度
- 5/5
- 見積もり時間
- 1週間以上
- 初心者へのやさしさ
- 35/100
- issue の種類
- バグ
- 明瞭さ
- おおむね明確
- 活発さ
- 停滞
- 技術スタック
- openapi, typescript
調査の方向性
まず、提供された Docker コマンドを fixture recursive-category-tree.yaml に対して実行し、生成された typescript-fetch の出力を調べます。swagger-parser PR #2332 と swagger-codegen が使用する依存関係パスを確認し、その後、$dynamicRef、$dynamicAnchor、$defs がどのようにコード生成へ到達するかを追跡します。パーサーの更新が利用可能になり、これらの fixture が any や空のインターフェースではなく具体的な型を生成すれば完了です。
索引モデルが issue の本文から書いたものです。
説明
Summary
Swagger Codegen v3 fails to produce meaningful types for OpenAPI 3.1 specs that use $dynamicRef / $dynamicAnchor. Schemas containing $dynamicAnchor result in empty interfaces or any types because swagger-parser does not preserve these fields through the parse/dereference cycle.
Reproduction
Minimal fixtures demonstrating the issue:
- Recursive category tree: https://github.com/aqeelat/openapi-dynamicref-adoption-tracker/blob/main/fixtures/recursive-category-tree.yaml
- Nested workspace resources: https://github.com/aqeelat/openapi-dynamicref-adoption-tracker/blob/main/fixtures/nested-workspace-resources.yaml
- Pagination/generic wrapper (named schemas): https://github.com/aqeelat/openapi-dynamicref-adoption-tracker/blob/main/fixtures/generic-schema-binding.yaml
docker run --rm \
-v $(pwd)/recursive-category-tree.yaml:/spec.json \
swaggerapi/swagger-codegen-cli-v3 generate \
-i /spec.json -l typescript-fetch -o /out
Result: interface PaginatedUserResponse {} — empty interface, all type information lost.
Root Cause
The failure originates in swagger-parser (shared dependency with OpenAPI Generator). The OAS 3.1 dereferencer:
- Crashes when component schemas have both
$idand$ref(resolves#/components/schemas/...against the$idURI instead of the document root) - Loses
$dynamicRef,$dynamicAnchor, and$defsduring the dereference cycle - Does not traverse
$defssub-schemas
A fix PR is open: https://github.com/swagger-api/swagger-parser/pull/2332
Expected Behavior
After the swagger-parser fix is merged and swagger-codegen updates its dependency:
- Specs with
$dynamicRef/$dynamicAnchorshould parse without errors. - The codegen layer should then be updated to resolve
$dynamicRefto concrete types instead of emittinganyor empty interfaces.
Blocking Dependency
- https://github.com/swagger-api/swagger-parser/pull/2332 — fixes parser-level
$dynamicRef/$dynamicAnchorsupport
Compatibility Evidence
A cross-generator compatibility matrix is tracked at:
https://github.com/aqeelat/openapi-dynamicref-adoption-tracker
This issue was drafted with assistance from AI tooling. The submitter is responsible for reviewing and validating the contents before submission.
- 主要言語
- Mustache
- スター
- 17.8k
- フォーク
- 5.9k
- 平均マージ
- 7時間 9分
- マージ済み PR（30日）
- 4
環境構築
- Dockerfile または Docker Compose ファイルあり
- プルリクエストのテンプレートあり
- コントリビューションガイドを読む
はじめの一歩
- issue を最後まで読み、次にプロジェクトのコントリビューションガイドを読みます。
- 着手することを issue にコメントします — 二人が同じ作業をするのを防げます。
- リポジトリをフォークし、ブランチを切って変更します。
- issue 番号を参照したプルリクエストを送ります。
swagger-api/swagger-codegen のほかの issue
-
難易度 2/5 1〜3時間 初心者へのやさしさ 78/100
swagger-api/swagger-codegen#12755 ·
-
難易度 2/5 1〜3時間 初心者へのやさしさ 62/100
swagger-api/swagger-codegen#12445 ·
-
security vulnerability
難易度 1/5 1時間未満 初心者へのやさしさ 62/100
swagger-api/swagger-codegen#11942 ·
-
[JAVA] Non compilable enums generated with property errorOnUnknownEnum=true対応中かも @HiagoW が 1469 日前に担当しました。 オープン
難易度 2/5 1〜3時間 初心者へのやさしさ 68/100
swagger-api/swagger-codegen#11812 · リアクション 1 件 ·
-
security vulnerability
難易度 2/5 1〜3時間 初心者へのやさしさ 65/100
swagger-api/swagger-codegen#11594 ·
swagger-api/swagger-codegen の issue をすべて見る
似ている issue
-
difficulty: easy
難易度 2/5 1〜3時間 初心者へのやさしさ 64/100
-
type: bug
難易度 2/5 1〜3時間 初心者へのやさしさ 79/100
メンテナーはふだん 1 日以内に返信
-
bug priority: P3 ready-for-agent
難易度 2/5 1〜3時間 初心者へのやさしさ 82/100
shep-pm/shep-kelpie#1332 ·
メンテナーはふだん 1 日以内に返信
-
難易度 2/5 1〜3時間 初心者へのやさしさ 72/100
メンテナーはふだん 1 日以内に返信
-
bug
難易度 2/5 1〜3時間 初心者へのやさしさ 76/100
aristocratos/btop#1945 ·
メンテナーはふだん 2 日以内に返信