swagger-api / swagger-api/swagger-codegen

Issue Resolving $ref in multi file spec

Open
#8,115 0 comments 0 reactions 0 assignees View on GitHub

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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.