[Bug]: Parameters components shouldn't be inlined with resolve option set to true

[Curs3W4ll]

Description

Following the doc, the resolve option should resolve refs (for parameters usage) from other external/relative sources/files and not replace ref usage by the inline version of the parameter. However, currently, the parameter ref is replaced by an inline version, while the component is still populated to POJO components.

Affected Version

e.g. 2.1.31

Earliest version the bug appears in (if known):
Seems to never have worked as expected.

Steps to Reproduce

1. Create the following yml files: 1. test.yml

openapi: 3.0.3
info:
  title: Test
  description: Test
  version: 0.0.1

paths:
  /test:
    parameters:
      - $ref: './test-components.yml#/components/parameters/TestIdQueryParameter'
    get:
      summary: Get all tests
      description: List tests
      responses:
        '200':
          description: OK

2. test-components.yml

openapi: 3.0.3
info:
  title: Portfolio Management API
  description: API to manage games portfolio
  version: 0.0.1

components:
  schemas:
    TestId:
      description: Test id
      type: string
      example: 1234
  parameters:
    TestIdQueryParameter:
      name: testId
      in: query
      description: Test id
      required: false
      schema:
        $ref: './test-components.yml#/components/schemas/TestId'

2. Use the following code to parse these files

package org.example;

import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.parser.OpenAPIV3Parser;
import io.swagger.v3.parser.core.models.ParseOptions;

public class Main {
    public static void main(String[] args) {
        ParseOptions options = new ParseOptions();
        options.setResolve(true);
        OpenAPI specs = new OpenAPIV3Parser().read("test.yml", null, options);

        System.out.println(specs);
    }
}

3. Check the parsed OpenAPI object

Expected Behavior

The parameters of the endpoint in the resulting OpenAPI object should look like this:

parameters: [
  ...
  $ref = "#/components/parameters/TestIdQueryParameter,
  ...
]

Actual Behavior

The parameters of the endpoint in the resulting OpenAPI object looks like this:

parameters: [
  ...
  $ref = null,
  ...
]

Logs / Stack Traces

Environment

• Java version: OpenJDK21
• Build tool: Gradle
• OS: MacOS 15.6

Additional Context

Checklist

• [x] I have searched the existing issues and this is not a duplicate.
• [x] I have provided sufficient information for maintainers to reproduce the issue.

[Curs3W4ll]

Probably related to https://github.com/swagger-api/swagger-parser/issues/2211

[marcelstoer]

@Curs3W4ll I agree that this is related to what @daniel-kmiecik closed. However, to me both issues show faulty generator behavior.

[ewaostrowska]

Hi @Curs3W4ll Thank you for reporting this issue. I have analyzed it and indeed it seems that the currant behavior is not correct for the parameters with external refs. Usage-site becomes fully inlined — which matches what resolveFully is supposed to do, not resolve. This is as well not aligned with the behavior for other types such (eg. responses).

I have crated an issue in our internal system and we will try to fix it as soon as possible. If you have any further information that could help us fix the issue that will be a great help for us!

[CHervaudBetclic]

Hello, any news about this @ewaostrowska ?