OpenApi (swagger v3) oneOfs are broken

[simllll]

Sorting

• I'm submitting a ...

  • bug report
  • feature request
  • support request

• I confirm that I

  • used the search to make sure that a similar issue hasn't already been submit

Expected Behavior

I discovered some weird issues with OpenAPI schemas when they are using "oneOf". I just want to clarify if this is an issue with tsoa or if there is a general bug with swagger's generators.
(see also swagger-api/swagger-codegen#9722)

Everything seems to work with swagger v2 : https://test.hokify.com/ats-api/swagger.yaml
But when generating the sawgger file I get the warnings of "Swagger 2.0 does not support union types beyond string literals.
If you would like to take advantage of this, please change tsoa.json's "specVersion" to 3."
So when I do that, everything looks fine, no warnings, no parsing errosr int he swagger UI console.. except that the generated clients (e.g. html2 and php) are broken. I tried to track it down, and found out that the issue lies somewhere in "oneOf" defintions (see issue 9722 in swagger-codegen for more details).

Current Behavior

The current generated openapi3 is not working correctly, unsure what's the real reason though.

Possible Solution

Output some warnings if this union type constilation is not correct, or fix oneOfs output if there is something wrong with this syntax.

Steps to Reproduce

1. https://editor.swagger.io/?url=https://test.hokify.com/ats-api/openapi.yaml
2. Generate Client -> HTML2 -> see that there are no schemas und you get javascript errors
3. https://editor.swagger.io/?url=https://test.hokify.com/ats-api/swagger.yaml <-- same defintion just in version 2
4. Generate Client -> HTML2 -> all works

same bugs appear with other clients (dynamic-html, php, ..etc).

Context (Environment)

Version of the library: 2.5.1
Version of NodeJS: 12.6.0

• Confirm you were using yarn not npm: [ ] <-- nope, I'm using npm

[dgreene1]

When I opened up your link (https://editor.swagger.io/?url=https://test.hokify.com/ats-api/openapi.yaml), the swagger editor UI shows no issues in the Swagger YAML that tsoa generated. If there were issue in what tsoa generated, then there would be a ❌ to the left of the bad yaml parts. But since there isn't, then this is not an issue with tsoa.

@simllll please file a bug with https://github.com/swagger-api/swagger-codegen

[simllll]

Thanks for clarifying, I actually thought so, just wanted to be sure.

Besides that, is there any specification out there for all the swagger parts? e.g. for "OneOf". I couldn't find anything that would describe the syntax or allowed values or anythign like this (except to this one page https://swagger.io/docs/specification/data-models/oneof-anyof-allof-not/ which is more like an example than a defintion I assume).

All the best, thanks again,
Simon

[dgreene1]

That documentation link you found is the best information I know of for understanding oneOf/allOf/anyOf. If you have more questions regarding the OpenAPI spec, I would recommend stack overflow.

As far as the generation issue, I believe the swagger codegen repo that I linked to should be able to fix your issue.

[WoH]

https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md

If you encounter something unexpected, please use this as a reference to check who is not following the spec.

[simllll]

Alright thanks again,
I have opened or actually renamed my already opened issue there, let's hope they find something :)
(ref swagger-api/swagger-codegen#9722)

Oh nice, thanks @WoH

Regards
Simon

[dgreene1]

Would you mind updating your referenced issue to clarify that the issue is not on the tsoa side?