swagger-api / swagger-api/swagger-codegen
Issue Resolving $ref in multi file spec
Nobody has claimed this yet.
- Dominant language
- Mustache
- Stars
- 17.8k
- Forks
- 6k
- PR merge metrics
- No merged PRs in 30d
Description
Swagger-codegen version
Codegen-Version : 2.4.0
Parser Version: 1.0.34
Description
In a multi file scenario where the file structure is as below:
|--- swagger.yaml
|--- responses /
| |--- responses.yaml
|--- entities /
| |--- common /
| | |--- common.yaml
If a response for a path in the swagger references responses/responses.yaml and the object structure here directly references a definition in common.yaml then the context of swagger.yaml must be used for addressing. Please note this is not specific to responses, i have reproduced consistently
If however the first reference is local then relative addressing behaves as per expected. Please see snippets below for further information
swagger.yaml
paths:
/pets:
get:
responses:
'400':
$ref: './responses/responses.yaml#/responses/invalidRequest'
responses.yaml
The below addressing only will work where as the expected addressing would be ../entities/common/common.yaml
responses:
invalidRequest:
description: The request was invalid
schema:
$ref: './entities/common/common.yaml#/definitions/errorModel'
If I change the above to the following it also works
responses:
invalidRequest:
description: The request was invalid
schema:
$ref: '#/definitions/errorModel'
definitions:
errorModel:
type: object
$ref: '../entities/common/common.yaml#/definitions/errorModel'
I have also observed that if the reference is an child object it needs to be relative to the initial calling file instead of the current file eg
definitions:
testDefinition:
type: object
properties:
propertyOne:
type: string
description: Test Property One
propertyTwo:
type: object
description: Test Property Two.
properties:
propertyThree:
type: array
description: Test Property Three
items:
$ref: './entities/common/common.yaml#/definitions/propertyThree'
minItems: 1
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Reproduce the reference resolution using swagger.yaml, responses/responses.yaml, and entities/common/common.yaml, including the nested propertyThree example. Compare resolution when the first reference is external with the local-reference workaround, and consider the issue done when nested $ref paths resolve relative to the file containing each reference without breaking the existing local case.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- yaml
- Domain
- api, tooling
- Issue type
- Bug
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 38/100