OpenAPITools / OpenAPITools/openapi-generator
[BUG] openapi-yaml generator produces invalid output with nested references
Nobody has claimed this yet.
- 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:
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
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 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