swagger-api / swagger-api/swagger-client

Support OpenAPI 3.1/3.2 $dynamicRef resolution with ApiDOM

Open
#4,223 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
JavaScript
Stars
2.7k
Forks
765
Avg merge
1d 1h
Merged PRs (30d)
6

Description

Summary

Proposed Swagger Client resolver work for OpenAPI 3.1/3.2 $dynamicRef schemas using ApiDOM. This issue is linked from the broader Swagger UI coordination issue so the prerequisite relationship is visible.

Reference implementation / showcase

The showcase repository includes OpenAPI examples used to validate that dynamic response envelopes and root-local #/components/... refs resolve as expected.

Related issues

  • Related coordination issue: swagger-api/swagger-ui#10912
  • Depends on ApiDOM core support: swagger-api/apidom#5176
  • Related user-facing Swagger UI bug: swagger-api/swagger-ui#10651
  • Related non-blocking Swagger UI display enhancement: swagger-api/swagger-ui#10913

Proposed scope

  • Delegate schemas with $dynamicRef to ApiDOM's dereference logic.
  • Resolve with full OpenAPI document context where dynamic scope requires root-level context.
  • Preserve compatibility for root-local #/components/... refs inside schemas that also declare absolute $id values.
  • Add regression coverage for a dynamic-ref response schema shape.

Contributor guide

Open the contributing guide

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.

Research direction

Start with the referenced ApiDOM core support issue #5176, then review the dynamic-ref examples in the adoption tracker and the existing Swagger Client resolver. Done means dynamicRef schemas resolve with full OpenAPI document context, root-local component refs remain compatible with absolute $id values, and regression coverage is added for the response schema shape.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript, openapi
Domain
api
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
48/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.