Don't downconvert openapi3.1 but instead generate 3.0 directly

[MichielVrins]

Summary

This PR fixes/implements the following bugs/features

• CDK synthesis time is excessively long for large zod schemas.

There is an issue that the synthesis time of a WSO2 api takes excessively long (Doesn't complete within 15minutes on an m1 mac) when using large Zod schemas(~300lines in my case). Some investigation with the debugger led to the discovery that the synth gets stuck somewhere in openapi-down-convert . We could fix the problem there, but there is also no need to downconvert the openapi spec, as zod-to-openapi supports generating 3.0.3 schemas directly. With this change it becomes near instant again for large schemas.

Breaking changes

• Direct usage of openapi 3.1 features in your zod schema will now no longer work. The following (Which is an anti pattern) will generate a 3.0.3 non compliant specification.

  SomeApiProperty: z
    .string()
    .nullish()
    .openapi({
      description:
        'Some description",
      type: ['string', 'null'],
    }),

In the above case, we're directly specifying 'null' as a possible type, but this is only supported in openapi 3.1. It should be noted that this is an anti pattern as the schema definition should be inferred from the Zod object directly and using the type property allows you to (unintentionally) lie about the specification.

There might be other cases like this, but I am unaware of those.

[flaviostutz]

Very nice catch, man!

If we can make it only 3.0 compatible it's even better! The thing is that for some reason when I implemented this zod-to-openapi only supported openapi 3.1 (maybe I was wrong at the time) while AWS API GW only supports openapi 3.0.

@MarcioMeier @erik-am @sergio-j Could you review this PR and also double check this questions about the zod-to-openapi to verify if now it really supports well OpenAPI 3.0 too?

[flaviostutz]

Let's release this as "beta" to test in our current applications because it might be a breaking change.

[MichielVrins]

What is the process to get it released as a beta version? Do I need to take any action for that?

[flaviostutz]

Never did it for an incoming PR. For doing that I will create a branch for you so we merge this to a local branch and then I create a tag for a beta release then.

Pls change your PR to target the branch feat/create-openapi3.0-directly

Pls tell me after you change it (there is a conflict to be solved)

[MichielVrins]

Hi @flaviostutz, I just changed the target branch and rebased it on top of main.

[flaviostutz]

I published this as 0.16.0-beta (https://github.com/flaviostutz/cdk-practical-constructs/actions/runs/13042505293)

Please test it :)