Fix unresolved relative $ref for examples in parameter definitions

Detailed description

In OpenAPI 3.0.3 specifications, when defining parameter examples via $ref that point to a relative YAML file path (e.g., ../../examples/rule/rule-parameters.yml#/StatusQueryParameter), swagger-parser does not resolve the example correctly. The unresolved reference results in missing examples in the parsed output.

Error output

java.lang.RuntimeException: Unable to load RELATIVE ref: ../../examples/rule/rule-parameters.yml path: /home/jorgerma/dev_apis/mre-rest-api-server/code/api-rest/target/tmp/openapi/rest
    at io.swagger.v3.parser.util.RefUtils.readExternalRef (RefUtils.java:220)
    at io.swagger.v3.parser.ResolverCache.loadRef (ResolverCache.java:156)
    at io.swagger.v3.parser.processors.ExternalRefProcessor.processRefToExternalExample (ExternalRefProcessor.java:740)
    at io.swagger.v3.parser.processors.ExampleProcessor.processReferenceExample (ExampleProcessor.java:45)
    at io.swagger.v3.parser.processors.ExampleProcessor.processExample (ExampleProcessor.java:30)
    at io.swagger.v3.parser.processors.ParameterProcessor.processParameter (ParameterProcessor.java:60)
    at io.swagger.v3.parser.processors.OperationProcessor.processOperation (OperationProcessor.java:43)
    at io.swagger.v3.parser.processors.PathsProcessor.processPaths (PathsProcessor.java:88)
    at io.swagger.v3.parser.OpenAPIResolver.resolve (OpenAPIResolver.java:72)
    at io.swagger.v3.parser.OpenAPIResolver.resolve (OpenAPIResolver.java:59)
    at io.swagger.v3.parser.OpenAPIV3Parser.resolve (OpenAPIV3Parser.java:240)
    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:687)

Example structure (tree)

openapi-rest.yml
paths
    └── rules
        └── rules.yml
examples
      └── rule
          └── rule-parameters.yml

• openapi-rest.yml references paths/rules/rules.yml via $ref.
• paths/rules/rules.yml parameter status includes an example via $ref: '../../examples/rule/rule-parameters.yml#/StatusQueryParameter'.
• examples/rule/rule-parameters.yml contains the target example definition.

Example YAML

openapi-rest.yml:

openapi: 3.0.3
info:
  title: Rules
  contact:
    name: myname
    email: zzz@mail.com
  description: API desgined for creating, updating, retrieving, and deleting rules and reference entities (reasons, processes).
  version: 1.0.2
security:
  - itxBearerAuth: []
servers:
  - description: The localhost API server.
    url: '{protocol}://localhost:{port}'
    variables:
     protocol:
       default: 'http'
     port:
       default: "8080"
tags:
  - name: Rule
    description: A rule defines when a product should be restricted from certain business processes based on specific conditions.
paths:
  /api/v1/rules:
    $ref: './paths/rules/rules.yml'

paths/rules/rules.yml:

get:
  tags:
    - Rule
  summary: Search rules (paginated)
  description: My description
  operationId: searchRulesPaginated
  parameters:
    - name: status
      in: query
      description: Filter by rule status (ACTIVE, INACTIVE, ARCHIVED).
      required: false
      schema:
        type: string
        enum: [ ACTIVE, INACTIVE, ARCHIVED ]
        description: "Current lifecycle status of the rule."
      examples:
        default:
          $ref: '../../examples/rule/rule-parameters.yml#/StatusQueryParameter'
  responses:
    '200':
      description: OK - Paginated list of rules successfully retrieved.
      content:
        application/json:
          schema:
            type: object

examples/rule/rule-parameters.yml:

StatusQueryParameter:
  value: 'ACTIVE'

Expected behaviour

swagger-parser should resolve all relative references for examples in parameter definitions and correctly include them in the parsed spec output.

Related issues:

• https://github.com/swagger-api/swagger-parser/issues/2091

Start with RefUtils.readExternalRef and ResolverCache.loadRef, then trace the example path through ExternalRefProcessor and ExampleProcessor using the YAML structure in the issue. Reproduce the relative parameter-example reference and verify that the parsed specification includes the referenced example without the unresolved-reference error.