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

Open
#16,262 1 comment 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

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 string and in the other file it is integer
  • it is used in /paths as 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

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.