Skip to content

fix(spec): inherit path-level parameters for cross-file $ref path items#10885

Open
yogeshwaran-c wants to merge 1 commit into
swagger-api:masterfrom
yogeshwaran-c:fix/path-item-parameters-cross-file-ref
Open

fix(spec): inherit path-level parameters for cross-file $ref path items#10885
yogeshwaran-c wants to merge 1 commit into
swagger-api:masterfrom
yogeshwaran-c:fix/path-item-parameters-cross-file-ref

Conversation

@yogeshwaran-c
Copy link
Copy Markdown

What kind of change does this PR introduce?

Bug fix.

What is the current behavior?

Path-level (a.k.a. "global") parameters declared on an OpenAPI path
item are not propagated to operations under that path when the path
item is reached through a cross-file $ref.

Reproduction (from issue):

  • openapi.yaml references a path from an external file:
    paths:
      /pets/{petId}:
        $ref: ./petstore.yaml#/paths/~1pets~1{petId}
  • petstore.yaml defines the path item with a path-level
    parameters array plus get and options operations.
  • The options operation declares no parameters of its own.

When the spec is loaded via openapi.yaml, the options operation
renders with the path-level parameter missing. When the same spec is
loaded directly via petstore.yaml, both operations correctly show
the parameter.

Closes #5667.

Root cause

swagger-client's generic normalize step
(resolver/strategies/generic/normalize.js) copies path-level
parameters into each operation under that path. swagger-ui depends on
this inheritance — operations are rendered using the operation-level
parameters array only.

When a path item is dereferenced from another file, swagger-ui lazily
resolves the subtree at ["paths", "/<path>"] via the
requestResolvedSubtree machinery in src/core/plugins/spec/actions.js.
The subtree resolver runs normalize against the root spec, but at
that point the root spec still has only { $ref: ... } at the path
position — there are no operations and no parameters to inherit
from. For OAS 3.0 the post-resolve normalize pass is skipped
(subtree-resolver/index.js passes skipNormalization: !isOpenAPI31),
so the inheritance never runs against the dereferenced output.

Fix

After a batch of subtrees is resolved, walk the resolved
paths object and, for each path item that has path-level
parameters, push those parameters into every operation that is
missing them. The merge is idempotent and uses the same duplicate
detection as swagger-client (matching by name, $ref, or $$ref),
so non-$ref'd paths already normalized by swagger-client are left
untouched.

What is the new behavior?

For both $ref'd and inline path items, path-level parameters appear
on every operation under that path. Existing operation-level
parameters take precedence (no duplicates created).

How Has This Been Tested?

  • New Jest unit tests in
    test/unit/core/plugins/spec/path-item-parameters.js covering:
    inherit when missing, no duplicates by name, no duplicates by $ref,
    no-op when path item has no parameters, ignore non-operation keys
    (summary, description, servers), create operation parameter
    array when missing.
  • New Cypress e2e test in test/e2e-cypress/e2e/bugs/5667.cy.js using
    a two-file fixture (5667-root.yaml, 5667-pets.yaml) that
    reproduces the issue exactly as reported. The tests fail without
    the fix (confirmed by reverting the fix and re-running) and pass
    with it.
  • Verified the surrounding spec-plugin unit suites
    (actions, selectors, reducer) still pass.

Additional context

The new helper lives at src/core/plugins/spec/path-item-parameters.js
and is intentionally scoped to JS-side plain-object manipulation so it
can run on the mutable resultMap accumulator produced by
debResolveSubtrees in
src/core/plugins/spec/actions.js. No other call sites are touched.

Path-level parameters declared on a path item should merge into every
operation under that path. swagger-client performs this inheritance in
its `normalize` step, but the step runs against the (still-$ref'd)
root spec when a path item is dereferenced from an external file. As a
result, operations under such path items (for example, an `options`
operation that declares no parameters of its own) never inherit the
path-level parameters and the UI renders them without the missing
parameter.

This change mirrors the swagger-client inheritance logic in the spec
plugin: after a batch of subtrees is resolved, each path item in the
resolved-subtrees result map has its path-level parameters merged into
every operation that is missing them. The merge is idempotent and uses
the same duplicate-detection logic as swagger-client (matching by
`name`, `$ref`, or `$$ref`), so non-$ref'd paths that have already
been normalized by swagger-client are unaffected.

Fixes swagger-api#5667
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Global parameters not visible when referenced through other definition.

1 participant