DEV Community

Discussion on: Which OpenAPI Codegen Should You Choose? openapi-typescript vs hey-api vs Orval vs Kubb

View post

Replies for: Amazing article. Adopted hey-api for about 2 years now! The only thing that bother me alot is the fact that it turns | null properties into unkno...

Collapse
 
nyaomaru profile image
nyaomaru •

Thank you for your comment and sharing this!

I checked my generated files again, and in this project I don’t seem to have the same issue.

My schema is OpenAPI 3.0.3 generated by drf-spectacular, and nullable string fields are represented with nullable: true.

For example:

playback_audio_file_path:
  type: string
  nullable: true
Enter fullscreen mode Exit fullscreen mode

is generated as:

playback_audio_file_path?: string | null;
Enter fullscreen mode Exit fullscreen mode

I also checked the generated type file, and string | null appears correctly in many places.

There are some unknown types in my generated output, but they seem to come from different schema shapes, such as additionalProperties, items: {}, or empty schemas like:

processing_json: {}
Enter fullscreen mode Exit fullscreen mode

So at least in my case, string | null itself is not being converted to unknown. 😿

I wonder if the issue may depend on the OpenAPI schema format, for example OpenAPI 3.1 style:

type:
  - string
  - "null"
Enter fullscreen mode Exit fullscreen mode

or maybe a specific combination of $ref, nullable, and the hey-api version difference. 🤔

Collapse
 
nyaomaru profile image
nyaomaru •

Small update: I also tried the OpenAPI 3.1 style, and it seems to work fine on my side too.

So maybe the issue depends on another condition, such as an OpenAPI schema version older than 3.x, or an older hey-api version than @hey-api/openapi-ts@0.96.1.

At least with my current setup, both OpenAPI 3.0.3 nullable: true and OpenAPI 3.1 type: ["string", "null"] seem to generate string | null correctly. And if you can't generate correctly with same version, it may be a difference of setup config. 🤔

Thread Thread
 
ergen35 profile image
Serge Eric Hotegni •

Thank you for your answers.
I'm rather using ElysiaJS as my backend framework. It have an openapi plugin that uses Scalar under the hood.
The current openapi version of the generated doc is 3.0.3 style
but there is no $ref in the document.
@hey-api/openapi-ts package is up to date (version 0.97.3)
Maybe i configured it wrong

Thread Thread
 
nyaomaru profile image
nyaomaru •

That makes sense. In my case, the OpenAPI schema is generated by drf-spectacular, and it does include many $ref entries under components.schemas.

So I think this may be an important difference:

  • my case: drf-spectacular / Django generates shared schemas with $ref
  • your case: ElysiaJS / Scalar seems to generate inline schemas without $ref 🤔

I guess this is probably not controlled by hey-api itself. hey-api is the consumer of the OpenAPI document, while ElysiaJS / Scalar or drf-spectacular is the producer of the OpenAPI document.

No $ref does not automatically mean the schema is broken, but maybe the specific inline nullable shape generated by ElysiaJS is causing hey-api to fall back to unknown.

So my current guess is that this may be related to the OpenAPI output shape from ElysiaJS / Scalar, rather than the hey-api config itself.

Hope this helps a bit! 😺

Thread Thread
 
ergen35 profile image
Serge Eric Hotegni •

Yes, it really helps.
I've found out that this feature is still experimental on Elysia framework.
I may have to find other ways to get a proper schema
Thank you very much!