fix(spec): inherit path-level parameters for cross-file $ref path items#10885
Open
yogeshwaran-c wants to merge 1 commit into
Open
fix(spec): inherit path-level parameters for cross-file $ref path items#10885yogeshwaran-c wants to merge 1 commit into
yogeshwaran-c wants to merge 1 commit into
Conversation
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
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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.yamlreferences a path from an external file:petstore.yamldefines the path item with a path-levelparametersarray plusgetandoptionsoperations.optionsoperation declares no parameters of its own.When the spec is loaded via
openapi.yaml, theoptionsoperationrenders with the path-level parameter missing. When the same spec is
loaded directly via
petstore.yaml, both operations correctly showthe parameter.
Closes #5667.
Root cause
swagger-client's generic
normalizestep(
resolver/strategies/generic/normalize.js) copies path-levelparameters into each operation under that path. swagger-ui depends on
this inheritance — operations are rendered using the operation-level
parametersarray only.When a path item is dereferenced from another file, swagger-ui lazily
resolves the subtree at
["paths", "/<path>"]via therequestResolvedSubtreemachinery insrc/core/plugins/spec/actions.js.The subtree resolver runs
normalizeagainst the root spec, but atthat point the root spec still has only
{ $ref: ... }at the pathposition — there are no operations and no
parametersto inheritfrom. For OAS 3.0 the post-resolve
normalizepass is skipped(
subtree-resolver/index.jspassesskipNormalization: !isOpenAPI31),so the inheritance never runs against the dereferenced output.
Fix
After a batch of subtrees is resolved, walk the resolved
pathsobject and, for each path item that has path-levelparameters, push those parameters into every operation that ismissing 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 leftuntouched.
What is the new behavior?
For both
$ref'd and inline path items, path-level parameters appearon every operation under that path. Existing operation-level
parameters take precedence (no duplicates created).
How Has This Been Tested?
test/unit/core/plugins/spec/path-item-parameters.jscovering: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 parameterarray when missing.
test/e2e-cypress/e2e/bugs/5667.cy.jsusinga two-file fixture (
5667-root.yaml,5667-pets.yaml) thatreproduces the issue exactly as reported. The tests fail without
the fix (confirmed by reverting the fix and re-running) and pass
with it.
(
actions,selectors,reducer) still pass.Additional context
The new helper lives at
src/core/plugins/spec/path-item-parameters.jsand is intentionally scoped to JS-side plain-object manipulation so it
can run on the mutable
resultMapaccumulator produced bydebResolveSubtreesinsrc/core/plugins/spec/actions.js. No other call sites are touched.