swagger-api / swagger-api/swagger-parser

Circular dependencies are not resolved properly with resolveFully

Open
#2,193 0 comments 0 reactions 0 assignees View on GitHub

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

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 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.