Repository navigation
fix: Rebase relative refs inside external path items only once (#2418) - #2419
ericschlarmann wants to merge 2 commits into
Conversation
ExternalRefProcessor.processPathItem rebases the relative schema and
example refs of an external path item onto the root document. Afterwards
PathsProcessor.updateRefs resolves the same refs again against the path
item's file. computePreprocessedRef skips a ref only when it does not
start with a dot or starts with "./". The second resolution is therefore
a no-op for an entry document at the root, and also for path items one
directory down. It can break once the rebased ref starts with "../":
with the entry in a subdirectory and the path item two directories down,
../../domain/sub/schemas.yaml becomes ../domain/domain/sub/schemas.yaml
("Unable to load RELATIVE ref"). Before 2.1.48 the unnormalized
concatenation of computeRelativeRef left
../domain/sub/../domain/sub/schemas.yaml, which the ".." fallback in
RefUtils.readExternalRef happened to recover.
ExternalRefProcessor now records the schemas and examples it rebased,
and PathsProcessor leaves those alone. Every other ref is rebased as
before.
|
|
||
| // One root document per case: the first ref that fails to load stops the resolution of every later one. | ||
| @DataProvider | ||
| public Object[][] refsInPathItemBelowSubdirectoryEntry() { |
There was a problem hiding this comment.
suggestion: The data provider is missing a few ref shapes.
It covers direct $ref, a nested property, parameters, and request and response examples. But the guard sits in a recursive method that also walks allOf, anyOf/oneOf, array items and callbacks, and a ref reached through one of those branches might not be marked.
Tests for items: {$ref: ...}, allOf: [{$ref: ...}] and a callback body schema would cover them.
There was a problem hiding this comment.
Added rows for items, allOf, anyOf, oneOf and a callback body schema.
| protected void updateRefs(Schema model, String pathRef) { | ||
| if(model.get$ref() != null) { | ||
| model.set$ref(computePreprocessedRef(model.get$ref(), pathRef)); | ||
| if(!externalRefProcessor.isRebasedOntoRootDocument(model)) { |
There was a problem hiding this comment.
question: Are discriminator mappings on composed schemas still consistent with this guard?
Say ExternalRefProcessor rebased the inner $ref and left the matching discriminator.mapping value alone. Then the mapping points somewhere other than the ref it describes.
A test row with a oneOf and a discriminator.mapping, inside an external path item below a subdirectory, would settle it.
There was a problem hiding this comment.
The guard can't split them: PathsProcessor only rewrites a mapping value together with its ref. Mapping values in a path item's request body, response and parameter schemas are never rebased at all, but that's an older bug, also on master, independent of this PR.
| protected void updateRefs(Schema model, String pathRef) { | ||
| if(model.get$ref() != null) { | ||
| model.set$ref(computePreprocessedRef(model.get$ref(), pathRef)); | ||
| if(!externalRefProcessor.isRebasedOntoRootDocument(model)) { |
There was a problem hiding this comment.
nitpick: The nested if here is right. Folding it into the outer condition with && sends a marked schema into the else if (properties) branches.
Someone cleaning up the code might make that change. Worth a comment so it stays nested:
// nested on purpose: a marked schema must not fall through to the sibling branches
diegourban
left a comment
There was a problem hiding this comment.
I ran into this myself after upgrading openapi-generator to 7.27.0, which bundles swagger-parser 2.1.48.
The proposed fix looks right to me. I would like the discriminator mapping question on composed schemas answered, or covered by a test, before this merges.
Adds data provider rows for refs reached through array items, allOf, anyOf and oneOf, which processPathItem rebases and marks; all four fail on master. Adds a callback request body schema, which only PathsProcessor rebases. The rows for refs only PathsProcessor rebases now go up one directory. With "../../" the ".." fallback in RefUtils.readExternalRef loaded the ref even when it was never rebased, so those rows could not catch a missing rebase. Comments the nested if in PathsProcessor.updateRefs(Schema): folded into the outer condition, a marked schema would fall through to the else-if branches.
Pull Request
Description
Fixes a regression in 2.1.48, still present in 2.1.49. With the root document in a subdirectory, a relative schema or example
$refinside an external path item two directories down was rebased twice.../../domain/sub/schemas.yamlbecame../domain/domain/sub/schemas.yaml, and resolving it failed withUnable to load RELATIVE ref.ExternalRefProcessor.processPathItemalready rebases these refs onto the root document.PathsProcessor.updateRefsthen resolved them again against the path item's file, andcomputePreprocessedRefonly recognizes a rebased ref when it does not start with a dot or starts with./. A rebased ref can start with../once the root document is not at the top.ExternalRefProcessornow records the schemas and examples it rebased (an identity set, scoped to the processor instancePathsProcessorowns), andPathsProcessor.updateRefsleaves those alone. Every other ref takes the same path as before, so the existingcomputeRef/computePreprocessedReftests are unchanged.Fixes: #2418
Type of Change
Checklist
Screenshots / Additional Context
New data-driven test
PathsProcessorTest.testRefInPathItemBelowSubdirectoryEntryIsRebasedOncewith resources insrc/test/resources/path-item-below-subdirectory-entry/: root documents inapi/, path items indomain/sub/. It uses one root document per case, because the first ref that fails to load stops the resolution of every later one.The eleven cases that
processPathItemrebases fail on master and pass with the fix:../../domain/sub/ref,./ref,schemas.yamlref,../../shared/),itemsref,allOfref,anyOfref,oneOfref.On master they come out as
../domain/domain/sub/...or../domain/shared/.... 2.1.47 also rebased them twice, but left the joined path un-normalized (../domain/sub/../domain/sub/schemas.yaml), which the..fallback inRefUtils.readExternalRefrecovered.Three cases that only
PathsProcessorrebases (a path-level parameter schema, a request body example and a callback request body schema) pass on both. They pin that every other ref is still rebased once. Their refs go up one directory only, because the..fallback would also load a../../ref that was never rebased.Full build
mvn teston JDK 17: all modules green.Also checked against a larger real-world multi-file spec set with three root documents, generating with openapi-generator 7.26.0 and this build swapped in: