[BUG] Cannot parse OpenAPI 3.1 specs using $dynamicRef / $dynamicAnchor (blocked by swagger-parser)

[aqeelat]

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:

1. Crashes when component schemas have both $id and $ref (resolves #/components/schemas/... against the $id URI instead of the document root)
2. Loses $dynamicRef, $dynamicAnchor, and $defs during the dereference cycle
3. Does not traverse $defs sub-schemas

A fix PR is open: swagger-api/swagger-parser#2332

Expected Behavior

After the swagger-parser fix is merged and swagger-codegen updates its dependency:

1. Specs with $dynamicRef / $dynamicAnchor should parse without errors.
2. The codegen layer should then be updated to resolve $dynamicRef to concrete types instead of emitting any or empty interfaces.

Blocking Dependency

• fix(parser-v3): preserve $dynamicRef/$dynamicAnchor and fix $id scope leak in OAS 3.1 dereferencer swagger-parser#2332 — fixes parser-level $dynamicRef / $dynamicAnchor support

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.