OpenAPITools / OpenAPITools/openapi-generator

[BUG] openapi-yaml generator produces invalid output with nested references

Open
#24,528 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Issue: Bug
Dominant language
Java
Stars
26.8k
Forks
7.7k
PR merge metrics
PR metrics pending

Description

Description

When using the structure described below as input to the openapi-yaml generator, the output is incorrect. The generation does not fail per se, but the output is malformed. There are multiple error messages

Failed to get the schema name

and

Error obtaining the datatype from ref

in the log, pointing to the cause of the problem.

openapi-generator version

Tested using the openapi-generator-cli Docker v7.24.0.
This does not appear to constitute a regression.

Expected vs. Actual

The difference is on the schemata for ArrayOfComplexTypes and NullableComplexType.

Actual:

openapi: 3.0.4
info:
  title: Open API Ref Test
  version: "1.0"
servers:
- url: /
paths:
  /simple:
    get:
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SimpleType"
          description: Simple return
  /arr:
    get:
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ArrayOfComplexTypes"
          description: description
  /null:
    get:
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NullableComplexType"
          description: description
components:
  schemas:
    ComplexType:
      properties:
        prop1:
          $ref: "#/components/schemas/SimpleType"
        prop2:
          items:
            $ref: "#/components/schemas/SimpleType"
          type: array
        prop3:
          allOf:
          - $ref: "#/components/schemas/SimpleType"
          nullable: true
      type: object
    SimpleType:
      example:
        value: value
      properties:
        value:
          type: string
      type: object
    ArrayOfComplexTypes:
      example:
        complexArray:
        - "{}"
        - "{}"
      properties:
        complexArray:
          items:
            $ref: ./swagger.yml#/components/schemas/ComplexType
          type: array
      type: object
    NullableComplexType:
      example:
        complexOrNull: ""
      properties:
        complexOrNull:
          allOf:
          - $ref: ./swagger.yml#/components/schemas/ComplexType
          nullable: true
      type: object

Expected:

openapi: 3.0.4
info:
  title: Open API Ref Test
  version: "1.0"
servers:
- url: /
paths:
  /simple:
    get:
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SimpleType"
          description: Simple return
  /arr:
    get:
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ArrayOfComplexTypes"
          description: description
  /null:
    get:
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NullableComplexType"
          description: description
components:
  schemas:
    ComplexType:
      properties:
        prop1:
          $ref: "#/components/schemas/SimpleType"
        prop2:
          items:
            $ref: "#/components/schemas/SimpleType"
          type: array
        prop3:
          allOf:
          - $ref: "#/components/schemas/SimpleType"
          nullable: true
      type: object
    SimpleType:
      example:
        value: value
      properties:
        value:
          type: string
      type: object
    ArrayOfComplexTypes:
      example:
        complexArray:
        - "{}"
        - "{}"
      properties:
        complexArray:
          items:
            $ref: "#/components/schemas/ComplexType"
          type: array
      type: object
    NullableComplexType:
      example:
        complexOrNull: ""
      properties:
        complexOrNull:
          allOf:
          - $ref: "#/components/schemas/ComplexType"
          nullable: true
      type: object
OpenAPI declaration file content or url

DIrectory structure:

Image

swagger.yml:

openapi: 3.0.4
info:
  version: "1.0"
  title: Open API Ref Test
paths:
  '/simple':
    get:
      responses:
        '200':
          description: Simple return
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimpleType'
  '/arr':
    get:
      responses:
        '200':
          description: description
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArrayOfComplexTypes'
  '/null':
    get:
      responses:
        '200':
          description: description
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NullableComplexType'

components:
  schemas:
    ComplexType:
      $ref: "./schemas/ComplexType.yml"
    SimpleType:
      $ref: "./schemas/SimpleType.yml"
    ArrayOfComplexTypes:
      $ref: "./schemas/ArrayOfComplexTypes.yml"
    NullableComplexType:
      $ref: "./schemas/NullableComplexType.yml"

schemas/SimpleType.yml

type: object
properties:
  value:
    type: string

schemas/ComplexType.yml:

type: object
properties:
  prop1:
    $ref: '../swagger.yml#/components/schemas/SimpleType'
  prop2:
    type: array
    items:
      $ref: '../swagger.yml#/components/schemas/SimpleType'
  prop3:
    nullable: true
    anyOf:
      - $ref: '../swagger.yml#/components/schemas/SimpleType'

ArrayOfComplexTypes.yml:

type: object
properties:
  complexArray:
    type: array
    items:
      $ref: '../swagger.yml#/components/schemas/ComplexType'

NullableComplexType.yml:

type: object
properties:
  complexOrNull:
    nullable: true
    anyOf:
      - $ref: '../swagger.yml#/components/schemas/ComplexType'
Generation Details
Steps to reproduce

Using the input described above, execute
docker run --rm -it --user $(id -u):$(id -g) --volume "${PWD}:/local" openapitools/openapi-generator-cli:v7.24.0 generate -g openapi-yaml -i local/swagger.yml -o local/out

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 by running the provided Docker command with swagger.yml and the four files under schemas/ to reproduce the malformed openapi-yaml output and logged errors. Compare the generated schemas for ArrayOfComplexTypes and NullableComplexType with the expected YAML; done means their external references resolve to the local #/components/schemas/ComplexType reference without errors.

Written by the indexing model from the issue text.

Assessment

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.