OpenAPITools / OpenAPITools/openapi-generator

[BUG] openapi-generators oneOfs are broken

Open
#4,431 1 comment 4 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Client: HTML 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)?
  • What's the version of OpenAPI Generator used?
  • Have you search for related issues/PRs?
  • What's the actual output vs expected output?
  • [Optional] Bounty to sponsor the fix (example)
Description

I've reported the issue already at the swagger-api, but swithed to this fork recently, unfortantely the issue is not solved here either.

Swagger Definition 2 works! https://test.hokify.com/ats-api/swagger.yaml
Swagger Deifntion 3 / Open API is broken when using "oneOf" with strings and objects. https://test.hokify.com/ats-api/openapi.yaml

running
java -jar /opt/openapi-generator/modules/openapi-generator-cli/target/openapi-generator-cli.jar generate -i dist/swagger/swagger.yaml -g html2 -o docs

generated a broken html2 output.

If I remove the occurences of "oneOf" and replace them by "type: string" it starts working.

                from:
                    oneOf:
                        -
                            type: string
                        -
                            properties:
                                name:
                                    type: string
                                address:
                                    type: string
                            required:
                                - address
                                - name
                            type: object
                    nullable: true
replyTo:
                    oneOf:
                        -
                            type: string
                        -
                            properties:
                                name:
                                    type: string
                                address:
                                    type: string
                            required:
                                - address
                                - name
                            type: object
                    nullable: true
 type:
                    oneOf:
                        -
                            $ref: '#/components/schemas/UserExtraType'
                        -
                            type: string
openapi-generator version

Building via docker openapitools/openapi-generator-cli:latest (updated 4 hours ago)

OpenAPI declaration file content or url

Swagger Definition 2 works! https://test.hokify.com/ats-api/swagger.yaml
Swagger Deifntion 3 / Open API is broken when using "oneOf" with strings and objects. https://test.hokify.com/ats-api/openapi.yaml

Command line used for generation

I'm geneating the defintions files with tsoa, I also opened an issue at tsoa's github page, and we checked that the issue is definitly not related to tsoa itself. The swagger file is valid, the generator seems to produce broken output here. See also https://github.com/lukeautry/tsoa/issues/474

Steps to reproduce

generate html2 docuematation with the open api defintion file:

java -jar /opt/openapi-generator/modules/openapi-generator-cli/target/openapi-generator-cli.jar generate -i dist/swagger/swagger.yaml -g html2 -o docs

Related issues/PRs

there are some issues reagrding "oneOf", but none that describes this bug in my opinion.

Suggest a fix

Unfortunatnely no idea how to fix this.. I assume it is something in the underlying library, due to the fact that a lot of output modes are affected (not only html2, also e.g. php client,..).

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 reported openapi-generator CLI command with the linked OpenAPI definition and compare the html2 output against the Swagger Definition 2 result. Inspect how the generator handles the three oneOf examples involving strings, objects, nullable values, and a schema reference; done means html2 documentation and the other affected outputs no longer break for these valid definitions.

Written by the indexing model from the issue text.

Assessment

Tech stack
java, openapi
Domain
api, documentation
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.