fix: External Refs with same name are ignored (#2055)

[ewaostrowska]

Pull Request

Description

When two external files each define a component with the same local name (e.g., both expose a schema called limit), the parser was silently discarding the second definition and pointing both usages at the first. This caused incorrect, incomplete resolved documents that were hard to diagnose because no error or warning was emitted. The same problem applied to all component types (schemas, parameters, responses, request bodies, headers, security schemes, links, examples, callbacks).

What was broken

Same-name external components were merged into one, losing data:

// POST /a-path references external_ref_1.json#/limit  ("There can be only 1")
// PUT  /a-path references external_ref_2.json#/limit  ("There can be only 2")

// Before: both operations resolved to the same component; second definition was silently dropped
openAPI.getComponents().getParameters().size() == 1  // wrong — only "limit" present

// After: each distinct external ref gets its own key
openAPI.getComponents().getParameters().size() == 2  // ✓  "limit" + "limit_1"
post.getParameters().get(0).getDescription()  // "There can be only 1" ✓
put .getParameters().get(0).getDescription()  // "There can be only 2" ✓

---

What changed

• ExternalRefProcessor — replaced the ad-hoc, per-type name-collision logic with a single call to ComponentNameAllocator.allocate(...). The old code had a different (buggy) implementation duplicated for every component type; the new code is a single loop that appends _N suffixes until a free or reusable slot is found.

• ComponentNameAllocator (new class) — centralises name allocation for all OpenAPI component maps. Uses pluggable policies for key lookup (exact vs. case-insensitive), ref-equivalence (delegated to ResolverCache), and value-equality reuse. Schemas use case-insensitive key lookup (matching existing behaviour); all other component types use exact-case keys.

---

Fixes: #2055

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

[ewaostrowska]

The solution maintains the different approach to the key sensitivity in between schema and non-schema components.

For schema component:
Pet and pet can be resolved to the same component

For non-schema component:
Pet and pet won't be resolved to the same component

I have decided to keep this separation as this would be a breaking change for the users and therefore if such appraoch is confirmed I would prefer to see it in a major version.