OpenAPITools / OpenAPITools/openapi-generator
[BUG] [openapi-yaml] Two specification cannot be merged if they have same-named but different schema component and they are used in array parameter
Nobody has claimed this yet.
- Dominant language
- Java
- Stars
- 26.8k
- Forks
- 7.7k
- PR merge metrics
- PR metrics pending
Description
Bug Report Checklist
- Have you provided a full/minimal spec to reproduce the issue?
- Have you validated the input using an OpenAPI validator (example)?
- Have you tested with the latest master to confirm the issue still exists?
- Have you searched for related issues/PRs?
- What's the actual output vs expected output?
- [Optional] Sponsorship to speed up the bug fix or feature request (example)
Description
Two specification cannot be merged together if
- they have same-named but different schema component
- e.g. in one file it is
stringand in the other file it isinteger
- e.g. in one file it is
- it is used in
/pathsas schema of array parameter
openapi-generator version
6.6.0, but it doesn't work in any other
OpenAPI declaration file content or url
spec1.yaml:
openapi: 3.0.1
info:
title: spec 1
version: 1.0.0
servers:
- url: http://localhost:8080
paths:
/getEmptyOne:
get:
operationId: getEmptyOne
parameters:
- name: elements
in: query
schema:
type: array
items:
$ref: '#/components/schemas/myType'
responses:
"204":
description: empty
components:
schemas:
myType:
type: string
spec2.yaml:
openapi: 3.0.1
info:
title: spec 2
version: 1.0.0
servers:
- url: http://localhost:8080
paths:
/getEmptyTwo:
get:
operationId: getEmptyTwo
parameters:
- name: elements
in: query
schema:
type: array
items:
$ref: '#/components/schemas/myType'
responses:
"204":
description: empty
components:
schemas:
myType:
type: integer
Generation Details
For maven plugin, there could be specified input directory, but for CLI the only way I know to do it is using helper "merging specification":
openapi-generator generate -g 'openapi-yaml' -i 'merged_spec12.yaml'
merged_spec12.yaml:
openapi: 3.0.1
info:
title: merged spec
version: 1.0.0
servers:
- url: http://localhost:8080
paths:
/getEmptyOne:
$ref: "./spec1.yaml#/paths/~1getEmptyOne"
/getEmptyTwo:
$ref: "./spec2.yaml#/paths/~1getEmptyTwo"
Steps to reproduce
Put all 3 files into one directory and run:
openapi-generator generate -g 'openapi-yaml' -i 'merged_spec12.yaml'
I have also created test sample repository in GitHub with that sample specifications and using maven plugin:
https://github.com/loplex/openapi-generator-test-1
Suggest a fix
The issue is related to renaming schema components.
If there are equivalent same-named schemas in two files, they are used in result file with no problem.
If there are different schemas with same name in two files (e.g. string and integer) and they are used as query parameters "directly", one of schema is renamed and both are used in result file with no problem.
But if in one of file the schema is used as schema for array query parameter, the one of schema is renamed, but they are referenced as ./<original_spec_file.yaml>#/components/schemas/<renamed_schema_name>, e.g.
./<original_spec_file.yaml>#/components/schemas/<original_schema_name>_1. But resulting file should not contain references to original files and what more, original file have no such component <renamed_schema_name> of course.
The reference should looks like #/components/schemas/<renamed_schema_name> with no original file reference in it.
The wrong behavior can be seen in my test sample repository https://github.com/loplex/openapi-generator-test-1 if property skipValidateSpec is set to true, e.g. by running mvn -DskipValidateSpec=true package
I have managed to fix the issue by modifying code in used library io.swagger.parser.v3:swagger-parser-v3, but I'm not sure with that fix, and also I'm not sure if it is really bug in that library because I have inputs only for openapi-generator.
But I tried it with many specification files with very high complexity, and it always works.
The fixed version of test sample, which uses openapi-generator-maven-plugin with modified dependency to modified version of swagger-parser-v3 can be seen here:
https://github.com/loplex/openapi-generator-test-1/tree/fixed
Cloned swagger-parser repo with my modification that fixed the issue for this case is here:
https://github.com/loplex/swagger-parser/tree/v2_1_16_bugfix1
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 reproducing the command using spec1.yaml, spec2.yaml, and merged_spec12.yaml, then inspect the openapi-generator merge path and the referenced swagger-parser-v3 behavior. Compare the generated OpenAPI YAML with the expected component references; done means renamed schemas are referenced locally without links to the original specification files.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- java
- Domain
- api, tooling
- Issue type
- Bug
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100