[BUG] Error resolving complex Reference with path parameter

Bug Report Checklist

• Have you provided a full/minimal spec to reproduce the issue?
• Have you validated the input using an OpenAPI validator (example)?
• Have you tested with the latest master to confirm the issue still exists?
• Have you searched for related issues/PRs?
• What's the actual output vs expected output?

Description

I have a root OpenAPI declaration file that makes paths references to another declaration's path in another file.
The path in question has a path parameter /my-resource/{my-path-param}

When trying to generate the models from the root declaration file, I'm getting the following error:

ERROR i.s.v.p.reference.ReferenceVisitor - Error resolving ./acls.yaml#/paths/~1acls~1{aclName}
 -Illegal character in fragment at index 27: ./acls.yaml#/paths/~1acls~1{aclName}

The problem is with the "{" behind the second ~1.

Other cases where no path parameter is provided, are working fine.

openapi-generator version

7.12.0

OpenAPI declaration file content or url

Root OpenAPI declaration file example

openapi: 3.1.2
info:
  title: Root OpenAPI declaration file
  version: 1.0.0
paths:
  /acls/{aclName}:
    $ref: 'acls.yaml#/paths/~1acls~1{aclName}'

Sub OpenAPI declaration file example 'acls.yaml'

openapi: 3.1.2
info:
  title: Jupiter agent Sub-swagger for Acls
  version: 1.0.0

paths:
  /acls/{aclName}:
    get:
      summary: Get an Acl by Name
      operationId: getAclByName
      parameters:
        - name: aclName
          in: path
          description: Name of acl to return
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: string

Generation Details

generatorName: spring
outputDir: generated
inputSpec: src/main/resources/api.yaml
additionalProperties:
  groupId: org.openapitools.openapi3
  artifactId: spring-acls
  snapshotVersion: "true"

Steps to reproduce

• create a root file root.yaml

openapi: 3.1.2
info:
  title: Root OpenAPI declaration file
  version: 1.0.0
paths:
  /acls/{aclName}:
    $ref: 'acls.yaml#/paths/~1acls~1{aclName}'

• at the same level, create a acls.yaml file

openapi: 3.1.2
info:
  title: Jupiter agent Sub-swagger for Acls
  version: 1.0.0

paths:
  /acls/{aclName}:
    get:
      summary: Get an Acl by Name
      operationId: getAclByName
      parameters:
        - name: aclName
          in: path
          description: Name of acl to return
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: string

• run the CLI

 openapi-generator-cli generate -i root.yaml --group-id org.openapitools.openapi3 --artifact-id spring-acls --artifact-version 0.0.1-SNAPSHOT -g spring -o generated

You should get the following error stack

[main] ERROR i.s.v.p.reference.ReferenceVisitor - Error resolving ./acls.yaml#/paths/~1acls~1{aclName}
java.net.URISyntaxException: Illegal character in fragment at index 27: ./acls.yaml#/paths/~1acls~1{aclName}
        at java.base/java.net.URI$Parser.fail(URI.java:2974)
        at java.base/java.net.URI$Parser.checkChars(URI.java:3145)
        at java.base/java.net.URI$Parser.parse(URI.java:3189)
        at java.base/java.net.URI.<init>(URI.java:623)
        at io.swagger.v3.parser.reference.ReferenceUtils.toBaseURI(ReferenceUtils.java:15)
        at io.swagger.v3.parser.reference.ReferenceVisitor.toBaseURI(ReferenceVisitor.java:65)
        at io.swagger.v3.parser.reference.ReferenceVisitor.toReference(ReferenceVisitor.java:69)
        at io.swagger.v3.parser.reference.ReferenceVisitor.resolveRef(ReferenceVisitor.java:205)
        at io.swagger.v3.parser.reference.ReferenceVisitor.visitPathItem(ReferenceVisitor.java:108)
        at io.swagger.v3.parser.reference.OpenAPI31Traverser.traversePathItem(OpenAPI31Traverser.java:383)
        at io.swagger.v3.parser.reference.OpenAPI31Traverser.traverseMap(OpenAPI31Traverser.java:933)
        at io.swagger.v3.parser.reference.OpenAPI31Traverser.traversePaths(OpenAPI31Traverser.java:197)
        at io.swagger.v3.parser.reference.OpenAPI31Traverser.traverseOpenApi(OpenAPI31Traverser.java:124)
        at io.swagger.v3.parser.reference.OpenAPI31Traverser.traverse(OpenAPI31Traverser.java:65)
        at io.swagger.v3.parser.reference.OpenAPIDereferencer31.dereference(OpenAPIDereferencer31.java:74)
        at io.swagger.v3.parser.OpenAPIV3Parser.resolve(OpenAPIV3Parser.java:227)
        at io.swagger.v3.parser.OpenAPIV3Parser.readContents(OpenAPIV3Parser.java:183)
        at io.swagger.v3.parser.OpenAPIV3Parser.readLocation(OpenAPIV3Parser.java:97)
        at io.swagger.parser.OpenAPIParser.readLocation(OpenAPIParser.java:16)
        at org.openapitools.codegen.config.CodegenConfigurator.toContext(CodegenConfigurator.java:686)
        at org.openapitools.codegen.config.CodegenConfigurator.toClientOptInput(CodegenConfigurator.java:744)
        at org.openapitools.codegen.cmd.Generate.execute(Generate.java:527)
        at org.openapitools.codegen.cmd.OpenApiGeneratorCommand.run(OpenApiGeneratorCommand.java:32)
        at org.openapitools.codegen.OpenAPIGenerator.main(OpenAPIGenerator.java:66)
[main] ERROR i.s.v.p.reference.ReferenceVisitor - Error resolving ./acls.yaml#/paths/~1acls~1{aclName}
java.net.URISyntaxException: Illegal character in fragment at index 27: ./acls.yaml#/paths/~1acls~1{aclName}
        at java.base/java.net.URI$Parser.fail(URI.java:2974)
        at java.base/java.net.URI$Parser.checkChars(URI.java:3145)
        at java.base/java.net.URI$Parser.parse(URI.java:3189)
        at java.base/java.net.URI.<init>(URI.java:623)
        at io.swagger.v3.parser.reference.ReferenceUtils.toBaseURI(ReferenceUtils.java:15)
        at io.swagger.v3.parser.reference.ReferenceVisitor.toBaseURI(ReferenceVisitor.java:65)
        at io.swagger.v3.parser.reference.ReferenceVisitor.toReference(ReferenceVisitor.java:69)
        at io.swagger.v3.parser.reference.ReferenceVisitor.resolveRef(ReferenceVisitor.java:205)
        at io.swagger.v3.parser.reference.ReferenceVisitor.visitPathItem(ReferenceVisitor.java:108)
        at io.swagger.v3.parser.reference.OpenAPI31Traverser.traversePathItem(OpenAPI31Traverser.java:383)
        at io.swagger.v3.parser.reference.OpenAPI31Traverser.traverseMap(OpenAPI31Traverser.java:933)
        at io.swagger.v3.parser.reference.OpenAPI31Traverser.traversePaths(OpenAPI31Traverser.java:197)
        at io.swagger.v3.parser.reference.OpenAPI31Traverser.traverseOpenApi(OpenAPI31Traverser.java:124)
        at io.swagger.v3.parser.reference.OpenAPI31Traverser.traverse(OpenAPI31Traverser.java:65)
        at io.swagger.v3.parser.reference.OpenAPIDereferencer31.dereference(OpenAPIDereferencer31.java:74)
        at io.swagger.v3.parser.OpenAPIV3Parser.resolve(OpenAPIV3Parser.java:227)
        at io.swagger.v3.parser.OpenAPIV3Parser.readContents(OpenAPIV3Parser.java:183)
        at io.swagger.v3.parser.OpenAPIV3Parser.readLocation(OpenAPIV3Parser.java:97)
        at io.swagger.parser.OpenAPIParser.readLocation(OpenAPIParser.java:16)
        at org.openapitools.codegen.config.CodegenConfigurator.toContext(CodegenConfigurator.java:686)
        at org.openapitools.codegen.config.CodegenConfigurator.toClientOptInput(CodegenConfigurator.java:744)
        at org.openapitools.codegen.cmd.Generate.execute(Generate.java:527)
        at org.openapitools.codegen.cmd.OpenApiGeneratorCommand.run(OpenApiGeneratorCommand.java:32)
        at org.openapitools.codegen.OpenAPIGenerator.main(OpenAPIGenerator.java:66)
Exception in thread "main" org.openapitools.codegen.SpecValidationException: There were issues with the specification. The option can be disabled via validateSpec (Maven/Gradle) or --skip-validate-spec (CLI).
 | Error count: 1, Warning count: 0
Errors:
        -Illegal character in fragment at index 27: ./acls.yaml#/paths/~1acls~1{aclName}

        at org.openapitools.codegen.config.CodegenConfigurator.toContext(CodegenConfigurator.java:717)
        at org.openapitools.codegen.config.CodegenConfigurator.toClientOptInput(CodegenConfigurator.java:744)
        at org.openapitools.codegen.cmd.Generate.execute(Generate.java:527)
        at org.openapitools.codegen.cmd.OpenApiGeneratorCommand.run(OpenApiGeneratorCommand.java:32)
        at org.openapitools.codegen.OpenAPIGenerator.main(OpenAPIGenerator.java:66)

Related issues/PRs

Suggest a fix

---

EDIT: (04/14/2025)
As an ugly workaround, it seems that replacing { by %7B and } by %7D can do the trick, but, unfortunately it does not respect the openapi specs

Start with the ReferenceUtils.toBaseURI and ReferenceVisitor paths shown in the stack trace, then reproduce the failure using the root.yaml, acls.yaml, and the openapi-generator CLI command. The fix is complete when a path reference containing a path parameter resolves without the Illegal character in fragment error and generation proceeds.