[AB-2620] feature/added example key matching

[AyushShri]

Summary

When converting a spec to a collection, pair a request example with a response example when they share the same example key name, and emit one Postman saved response per matched key — instead of collapsing everything to the first example. When nothing matches, fall back to the legacy first-request + first-response behavior (zero regression).

Problem

An OpenAPI operation can define multiple named examples for a request body and for each response (e.g. an admin example and a user example). Today, when we convert a spec to a Postman collection — and sync it back — we keep only the first example and drop the rest.

This was an intentional earlier decision: OpenAPI doesn't define any relationship or ordering between a request example and a response example, so automatically pairing them was a guess that could change between runs and broke 2-way sync. To stay safe, we collapsed everything to the first example.

A customer now needs all of their examples to come through. So we need to surface multiple examples without reintroducing that non-determinism — the spec ↔ collection round trip must stay deterministic and lossless (syncing one direction and back must reconstruct the original).

Approach:

pair a request example with a response example only when they share the same example key name (e.g. both called admin). Matched pairs become separate saved responses in the collection; anything unmatched falls back to today's "first example" behavior. This keeps the mapping explicit and reversible.

This is the forward (spec → collection) half of multi-example round-trip support; the reverse half lives in @postman/collection-to-openapi PR.

What changed (libV2/CollectionGeneration/schemaUtils.js)

• For each (operation, statusCode): compute the matching keys between the request examples and that code's response examples. For each matched key, emit a saved response with response.body = the response example and originalRequest.body = the matched request example.
• No matching keys for a code → fall back to the first request example + first response example (single saved response) — unchanged legacy path.
• Removed response-code-as-key matching (out of MVP scope; it now falls back to first).
• The saved-response name stays tied to the response-level description, so it round-trips to the OAS response description on sync. Pairing identity rides on the example key, not the name.

Scope / non-goals

• Matching-key pairing only (Option A). Differing-key pairing via a vendor extension, many-to-many (N×N), and partial-pairing materialization are out of scope.
• The request item's live body remains a single example; per-example request bodies are reflected only in each saved response's originalRequest.

Tests

• test/unit/convertV2.test.js — updated the multi-example cases to the matching-key behavior; added "falls back to first request and first response example when no request/response keys match".
• test/unit/convertV2WithTypes.test.js — added a matching-key test and a fallback test (also asserting type extraction).

Fixes:

AB-2620 https://postmanlabs.atlassian.net/browse/AB-2620

Test plan

• npm run test-unit (convertV2, convertV2WithTypes, CollectionGenerationAndSyncing) — green
• lint

[github-actions]

unit test code coverage

Lines	Statements	Branches	Functions
	88.98% (5888/6617)	80.8% (3856/4772)	94.02% (866/921)

Coverage Breakdown • (89%)

File	% Stmts	% Branch	% Funcs	% Lines	Uncovered Line #s
All files	88.98	80.8	94.02	89.09
libV2/CollectionGeneration	90.93	82.52	95.05	90.97
schemaUtils.js	94.08	88.42	99.03	94.33	...2639–2645, 2691

[github-actions]

integration test code coverage

Lines	Statements	Branches	Functions
	19.73% (2116/10721)	13.43% (1002/7456)	20.73% (248/1196)

Coverage Breakdown • (20%)

File	% Stmts	% Branch	% Funcs	% Lines	Uncovered Line #s
All files	19.73	13.43	20.73	20.03
libV2/CollectionGeneration	5.55	0	0	5.61
schemaUtils.js	7.84	0	0	7.91	...2761, 2774–2834

[Copilot]

Pull request overview

This PR updates the OpenAPI → Postman collection conversion logic to emit multiple saved responses when request/response examples share the same example key, while preserving deterministic behavior by falling back to the legacy “first request + first response” path when no keys match.

Changes:

• Updated example pairing logic to match request/response examples strictly by shared example key name (case-insensitive), otherwise fall back to first-only (no positional matching).
• Updated response generation to emit one Postman saved response per matched example pair for a given status code.
• Added/updated unit tests (with and without type extraction) to cover matching-key pairing and fallback behavior.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.

File	Description
libV2/CollectionGeneration/schemaUtils.js	Implements matching-key pairing for examples, removes positional matching behavior, and emits multiple saved responses per status code where applicable.
test/unit/convertV2.test.js	Updates/extends convertV2 unit tests to assert multi-example pairing by key and first-only fallback when no keys match.
test/unit/convertV2WithTypes.test.js	Adds coverage for matching-key pairing and first-only fallback while asserting extracted types remain correct.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[AyushShri]

addressed

[Copilot]

Pull request overview

Copilot reviewed 8 out of 8 changed files in this pull request and generated 2 comments.

[Copilot]

Pull request overview

Copilot reviewed 9 out of 9 changed files in this pull request and generated 2 comments.