Support Path Item references (OpenAPI 3.1 only)

[petershaw]

A file that works in openapi generator does not work in openapi-generator. The section that causes the error is:

paths:
  /documents:
    $ref: './paths/documents.yaml#/documents'
  /documents/{document-ident}:
    $ref: './paths/documents.yaml#/documents-detail'

in the root file.

Error:

error: Inconsistency encountered when parsing `Vendor Extension` under the `/documents` path: Found at least one vendor extension property that does not begin with the required 'x-' prefix. Invalid properties: [ $ref ].

We always have our paths in separate files for various reasons. This never was a problem before so I think swift-openapi-generator should implement it. ;)

[czechboy0]

cc @mattpolzin as I suspect this support would first need to be added in OpenAPIKit

[czechboy0]

This is specifically about Path Item references, not external references, which we're discussing separately in #25.

[mattpolzin]

Tracking this as a bug here: mattpolzin/OpenAPIKit#280

[mattpolzin]

This bug should be fixed with the new alpha release. Note the breaking changes described on the Release page: https://github.com/mattpolzin/OpenAPIKit/releases/tag/3.0.0-alpha.9

[czechboy0]

Amazing, thank you @mattpolzin. I marked this issue as unblocked now, for anyone who wants to pick it up.