ResolveFully fails on internal references when the initial spec is read from a file URL

[klease]

Hi,
While testing the new 3.1.0 feature of a pathItem in components, I found that resolveFully is not replacing internal references such as $ref: "#/components/pathItems/getPet" when the initial URL to the spec is a file:// URL. There is an exception in the log like this:

java.io.FileNotFoundException: file:/...../target/test-classes/petstore-3.1.yaml (Aucun fichier ou dossier de ce type)
        at java.io.FileInputStream.open0(Native Method) ~[?:?]
        at java.io.FileInputStream.open(FileInputStream.java:216) ~[?:?]
        at java.io.FileInputStream.<init>(FileInputStream.java:157) ~[?:?]
        at java.io.FileInputStream.<init>(FileInputStream.java:111) ~[?:?]
        at io.swagger.v3.parser.reference.Visitor.readFile(Visitor.java:66) ~[swagger-parser-v3-2.1.13.jar:2.1.13]
        at io.swagger.v3.parser.reference.Visitor.readURI(Visitor.java:84) ~[swagger-parser-v3-2.1.13.jar:2.1.13]
        at io.swagger.v3.parser.reference.ReferenceVisitor.parse(ReferenceVisitor.java:279) ~[swagger-parser-v3-2.1.13.jar:2.1.13]

This is true for any internal reference from the initial specification.
The Visitor.readFile() method needs to transform the file URL to a valid path.
I've never contributed to swagger before but I could create a test case and PR for this issue.

[jpommerening]

Yup, same here, Swagger Parser 2.1.22.
I have a very basic OpenAPI 3.1 file without any external references and when I use options.setResolve(), the FileNotFoundException is logged and SwaggerParseResult contains the caught exception message.

Interestingly the issue only happens with OpenAPI 3.1 (not with OpenAPI 3.0, or Swagger 2.0).

Here's some more of the stack trace:

java.io.FileNotFoundException: file:/.../test-3.1.openapi.json (No such file or directory)
 	at java.base/java.io.FileInputStream.open0(Native Method)
 	at java.base/java.io.FileInputStream.open(FileInputStream.java:219)
 	at java.base/java.io.FileInputStream.<init>(FileInputStream.java:157)
 	at java.base/java.io.FileInputStream.<init>(FileInputStream.java:112)
 	at io.swagger.v3.parser.reference.Visitor.readFile(Visitor.java:66)
 	at io.swagger.v3.parser.reference.Visitor.readURI(Visitor.java:84)
 	at io.swagger.v3.parser.reference.ReferenceVisitor.parse(ReferenceVisitor.java:305)
 	at io.swagger.v3.parser.reference.ReferenceVisitor.resolveSchemaRef(ReferenceVisitor.java:241)
 	at io.swagger.v3.parser.reference.ReferenceVisitor.visitSchema(ReferenceVisitor.java:141)

Should Visitor.readURI() maybe strip the file: prefix before calling Visitor.readFile() or use File(URI) rather than File(String)?

edit

Workaround: strip the file: scheme from the URI before passing it to parseLocation().
Instead of using getResource( "x" ).toURI(), you can use URI.create( getResource( "x" ).toString().replaceFirst( "^file:", "" ) …

[pavelkryl]

Still reproducible on the latest swagger-parser 2.1.43, and there's a quieter but higher-impact variant of this same file://-base-URI handling that's worth recording here because it bites code generators hard.

Variant: resolve=true, resolveFully=false → internal $refs are silently inlined (not just failing)

With OAS 3.1, ParseOptions.setResolve(true) and setResolveFully(false), loading a spec that contains only internal (#/components/...) refs:

• by filesystem path → internal $refs are preserved (correct)
• by file:// URL → internal $refs are inlined / replaced by a copy (the $ref is gone), even though resolveFully is false

So callers that explicitly ask not to fully resolve still lose their $refs purely because the spec was handed in as a URL. The 3.1 dereferencer in OpenAPIV3Parser.resolve(...) runs whenever isResolve() || isResolveFully() is true (not only for resolveFully), and with a file:// base URI it dereferences internal pointers as if they were external file refs (Visitor.readURI → readFile(resolved.getPath())).

Minimal, dependency-free reproduction

reuse.yaml (OAS 3.1, one reused internal $ref):

openapi: 3.1.0
info: { title: t, version: "1" }
paths:
  /fees:
    get:
      responses:
        "200":
          description: ok
          content:
            application/json:
              schema: { $ref: "#/components/schemas/FeeListResponse" }
components:
  schemas:
    FeeValues: { type: object, properties: { amount: { type: integer } } }
    FeeListResponse:
      type: object
      properties:
        fees:
          type: array
          items: { $ref: "#/components/schemas/FeeValues" }

ParseOptions o = new ParseOptions();
o.setResolve(true);
o.setResolveFully(false);   // explicitly: do NOT inline

for (String loc : new String[]{ path, Paths.get(path).toUri().toString() }) {
    OpenAPI api = new OpenAPIV3Parser().readLocation(loc, null, o).getOpenAPI();
    Schema fees = (Schema) api.getComponents().getSchemas()
            .get("FeeListResponse").getProperties().get("fees");
    System.out.println(loc + "  ->  items.$ref = " + fees.getItems().get$ref());
}

Output:

/abs/path/reuse.yaml                 ->  items.$ref = #/components/schemas/FeeValues   (preserved)
file:///abs/path/reuse.yaml          ->  items.$ref = null                             (inlined)

The same spec in OAS 3.0 preserves the $ref under both path and file:// load — this is 3.1-only.

Version matrix (file:// URI, 3.1, resolveFully=false): reproduces on 2.1.22, 2.1.31, 2.1.37, 2.1.38, 2.1.43.

Why it matters downstream (openapi-generator / quarkus-openapi-generator)

openapi-generator's CodegenConfigurator calls readLocation(...) with resolve=true, resolveFully=false and relies on $refs being preserved (it has its own InlineModelResolver). When a caller passes the spec as a URL, the refs come back inlined, so InlineModelResolver re-extracts each use-site into its own model (<Parent><Prop>Inner, <Parent><Prop> for nullable anyOf, <Operation>Request for request bodies) and the canonical component is emitted but orphaned (generated, never referenced).

• openapi-generator CLI loads by path → unaffected.
• The Maven/Gradle plugins and quarkus-openapi-generator (which does configurator.setInputSpec(specFilePath.toUri().toString())) load by URL → every reused component is duplicated per use-site, producing large numbers of orphaned/cloned models.

Likely the same root cause as #2201 and #1166. I'm happy to open a PR — the fix looks localized to how the 3.1 dereferencer resolves a file:// base URI for purely-internal (#/...) pointers (it should treat in-document fragment refs as internal regardless of whether the root document was loaded by path or by file:// URL).