Add pathItem reference resolution for OpenAPI 3.1 specs

[animeshjajoopostman]

Description

Add pathItem reference resolution for OpenAPI 3.1 specs

When bundling multifile OpenAPI 3.1 specifications, the bundler correctly creates $ref pointers in the paths object that reference components.pathItems (which is valid in OpenAPI 3.1). However, convertV2() and convertV2WithTypes() expect path operations to be inline, not referenced. This resulted in empty collections with folders but no actual requests.

Testing Videos

Before

https://www.loom.com/share/560803f154af4b43884e1ad06e6d64c4?sid=49488c91-6513-484d-bf77-3c94eb9a174c

AFTER

https://www.loom.com/share/0aa0e641302141d594f39b83509b55fe?sid=0afb4781-4918-46b7-b10c-a399726b462f

[github-actions]

unit test code coverage

Lines	Statements	Branches	Functions
	89.22% (5824/6527)	80.88% (3825/4729)	93.79% (862/919)

Coverage Breakdown • (89%)

File	% Stmts	% Branch	% Funcs	% Lines	Uncovered Line #s
All files	89.22	80.88	93.79	89.34

report-only-changed-files is enabled. No files were changed in this commit :)

[github-actions]

integration test code coverage

Lines	Statements	Branches	Functions
	19.26% (2048/10632)	13.46% (1002/7441)	19.91% (236/1185)

Coverage Breakdown • (19%)

File	% Stmts	% Branch	% Funcs	% Lines	Uncovered Line #s
All files	19.26	13.46	19.91	19.54

report-only-changed-files is enabled. No files were changed in this commit :)

[barshan23]

Why is this a requirement ?

[animeshjajoopostman]

I'm assuming you're asking this for the typeof check.

Type checking for string refs ensures valid spec references are being used. Instead of throwing an error, I'm ignoring that path reference.

Also .match() on line 391 will throw an error if the ref is not a string.

[barshan23]

No I meant about this match pattern itself ? Can you share the documentation link that mentions that the $refs needs to follow the pattern ?

[animeshjajoopostman]

OAS 3.1 Components: https://spec.openapis.org/oas/v3.1.0.html#components-object

$refs are defined similar to other versions, but generateObjectName() adds the file extension while bundling.

"referenceMap": {
    "#/components/pathItems/paths_pets.yaml": {
        "path": "paths/pets.yaml",
        "type": "component"
    },
}