swagger-api / swagger-api/swagger-parser
Circular dependencies are not resolved properly with resolveFully
Nobody has claimed this yet.
- Dominant language
- Java
- Stars
- 867
- Forks
- 560
- Avg merge
- 2d 21h
- Merged PRs (30d)
- 7
Description
OpenAPIV3Parser does not seem to work as one would expect when openapi components have circular dependencies of any kind.
Expected behaviour:
All $refs are resolved. If the schema references itself or has a cycle then the same Schema object should be used multiple times.
For example, TreeNode schema that has property parentNode of type TreeNode should be resolved to the ObjectSchema instance (let's say ObjectSchema@123) with property parentNode equal to the same instance (ObjectSchema@123)
Actual behaviour:
First $ref is resolved but the following references are not resolved and remain only with non-null $ref field.
From the example above we get properly resolved ObjectSchema instance with property parentNode which is in turn not resolved and remains a Schema without any properties but with $ref pointing to TreeNode.
Here is an openapi with 3 problematic cases I tested. The working example can be found here.
It this is indeed a bug, I could try to contribute a fix.
openapi: 3.0.0
info:
title: Circular Reference Example
version: 1.0.0
components:
schemas:
TreeNode:
type: object
properties:
id:
type: string
value:
$ref: '#/components/schemas/TreeNodeValue' # Circular reference through another object
parentNode:
$ref: '#/components/schemas/TreeNode' # Circular reference in object
childNodes:
type: array
items:
$ref: '#/components/schemas/TreeNode' # Circular reference in array
required:
- name
TreeNodeValue:
type: object
properties:
val:
type: string
ofNode:
$ref: '#/components/schemas/TreeNode' # Circular reference through another object
paths:
/tree/{id}:
get:
summary: Get a TreeNode
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
'200':
description: TreeNode found
content:
application/json:
schema:
$ref: '#/components/schemas/TreeNode'
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 at the OpenAPIV3Parser entry point and reproduce the three circular-reference cases from the linked SwaggerTest.java example. Compare the resolved schemas with the expected behavior: every $ref should resolve, and cyclic references should reuse the same Schema object. The issue's YAML provides the cases to verify.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- java, openapi
- Domain
- api
- Issue type
- Bug
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 42/100