swagger-api / swagger-api/swagger-parser

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

Open
#2,216 6 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Bug
Dominant language
Java
Stars
867
Forks
560
Avg merge
2d 21h
Merged PRs (30d)
7

Description

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'
  1. 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);
    }
}
  1. 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

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

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the OpenAPIV3Parser entry point and the ParseOptions handling for resolve=true, using test.yml and test-components.yml to reproduce the behavior. Inspect how the parsed OpenAPI object represents the external parameter reference. Done means the parameter remains a local $ref to components/parameters/TestIdQueryParameter while external references are resolved as expected.

Written by the indexing model from the issue text.

Assessment

Tech stack
java
Domain
api
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.