swagger-api / swagger-api/swagger-parser
[Bug]: Parameters components shouldn't be inlined with resolve option set to true
Nobody has claimed this yet.
- 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
- 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'
- 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);
}
}
- Check the parsed
OpenAPIobject
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
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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