Ref resolver doesn't follow JSON Reference specification

Using io.swagger.codegen.v3:swagger-codegen:3.0.7 it fails to resolve $ref aka JSON Reference. Calling new OpenAPIV3Parser().read("src/openapi/openapi.yaml") fails with:

java.lang.RuntimeException: Unable to load RELATIVE ref: ./schemas/index.yaml path: <path>/src/openapi

The API is not a Hello World so it is split to >30 files. Directory structure snippet:

openapi
├── components
│   ├── index.yaml
│   ├── parameters
│   │   └── index.yaml
│   ├── responses
│   │   └── index.yaml
│   └── schemas
│       ├── connection.yaml
│       ├── connectiondirection.yaml
│       ├── connectors
│       │   ├── connector.yaml
│       │    ...
│       │   └── impl
│       │       ├── foo.yaml
│       │        ...
│       │       └── bar.yaml
│       ├── index.yaml
│       ├── info.yaml
│        ...
│       ├── reports.yaml
│       ├── transaction.yaml
│       └── workflow.yaml
└── openapi.yaml

The issue is caused by a “nested” relative referencing:

/openapi.yaml
    $ref: "./components/index.yaml#foo"
/components/index.yaml
    foo:
       $ref: "./schemas/index.yaml#bar"
/components/schemas/index.yaml
    bar:
       ...

According to JSON Reference:

Resolution is performed relative to the referring document.

This means the ./schemas/index.yaml reference inside /components/index.yaml file shouldn’t be resolved against the root directory but /components directory! On a first sight the io.swagger.v3.parser.ResolverCache.loadRef() operates with a static parentDirectory only.

This is a well-documented feature and different parsers work just fine.

[yuri1969]

FYI: I workaround this issue by flattening the whole directory structure a to single humongous YAML file using Node-based swagger-parser as a pre-processor in our CI pipeline.

[apurvaSAP]

I am trying to reference a local file Money.json in another schema provisions.json using $ref as mentioned below:

provisions.json

"responses": { "200": { "schema": { "$ref": "resources/json/Money.json#/definitions/Money" },

resources/json/Money.json

"definitions": { "Money": { "type": "object", "properties": { "amount": { "type": "number", "format": "bigdecimal", "description": "Amount" }, "currency": { "type": "string", "description": "A unique internal identifier for the currency" } } }

I want to customize the resource loading behaviour as per my requirement. For example I want to restrict the loading of remote URLs and allow local refs or interpret the ref URLs as per my application requirements. Is it possible to maybe register my custom reference resolver and loader. From the code I see RefUtils.java tries to load it but how can I customize it ?