Fix: resolution of external refs inside path items with templated fragments (#2033)

[ewaostrowska]

Pull Request

Description

When an external path item is referenced with a URL whose fragment contains an OpenAPI path template (e.g. traceability/nodes.yaml#/paths/~1nodes~1{uuid}~1rights), any response headers, links, or examples inside that path item that point to further external files fail to resolve. Instead of the correct component, the reference ends up pointing at the parent path item, which is the wrong type.

What was broken

processRefHeaders, processRefLinks, and processRefExamples each computed the external file path correctly,
but then passed the full $ref (fragment included) down to the nested processor. Inside processRefHeader, the join call constructed new URI(source) with that string. The raw { character is not valid in a URI, so the constructor throwed, the catch block silently returns the original source string, and the header ends up pointing at the parent path item rather than common-spec-openapi.yaml#/components/headers/Content-Range.

// Before: header.$ref = "traceability/nodes.yaml#/paths/~1nodes~1{uuid}~1rights"  (wrong)
// After:  header.$ref = "#/components/headers/Content-Range"  ✓

The same bug affected links and examples in the same code path.

What changed

• ExternalRefProcessor.processRefHeaders (~line 920): passes file instead of $ref to processRefHeader, so the join operation never sees the raw-brace fragment.
• ExternalRefProcessor.processRefExamples (~line 870): same fix for examples.
• ExternalRefProcessor.processRefLinks (~line 931): same fix for links.

Also refactores processRef into a separate method to avoid duplicating code.f

This mirrors a fix applied to the schema code path which had the same problem.

Fixes: #2033

Type of Change

• 🐛 Bug fix
• ✨ New feature
• ♻️ Refactor (non-breaking change)
• 🧪 Tests
• 📝 Documentation
• 🧹 Chore (build or tooling)

Checklist

• I have added/updated tests as needed
• I have added/updated documentation where applicable
• The PR title is descriptive
• The code builds and passes tests locally
• I have linked related issues (if any)

Screenshots / Additional Context