apple / apple/swift-openapi-generator

Support Path Item references (OpenAPI 3.1 only)

Open
#128 12 comments 0 reactions 0 assignees View on GitHub
area/generator area/openapi kind/enhancement
Dominant language
Swift
Stars
2k
Forks
182
Avg merge
13h 28m
Merged PRs (30d)
5

Description

A file that works in openapi generator does not work in openapi-generator. The section that causes the error is:
```yaml
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. ;)

Contributor guide

Open the contributing guide

Research direction

Start by reproducing the supplied OpenAPI 3.1 YAML with path items referenced from a separate file, then trace where the parser treats `$ref` under `/documents` as a vendor extension. Done means valid Path Item references are accepted without the reported error while other invalid vendor extensions remain rejected.

Written by the indexing model from the issue text.

Assessment

Tech stack
openapi, swift
Domain
api
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.